py-jsm-asset 1.0.1
Python Library for handling Jira Service Manager asset. Provides a class to read, modify and add objects to asset schema.
Requires Python: >=3.9

# py-jsm-asset


## Name
py-jsm-asset

## Description
Python Library for handling Jira Service Manager asset. Provides a class to read, modify and add objects to asset schema.
In _app_ some practical example. 

## Confluence
https://confluence.infn.it/display/LDCG/JIRA+Asset+Management

## Installation


It requires *python >= 3.9*


First: Check the Requirements
If you need to install requests, just do it running 
```
pip3 install -r requirements.txt
```


 Import  the py_jsm_asset.py into your code:
 Put the py_jsm_asset.py file in the same folder of your application.
 Import the file into the code:
 ```
 from py_jsm_asset  import RestAssetCommunicator
 ```

 
 ## Test
 
 Go into *py_jsm_asset/tests* . You must have a *token.txt* where there is the asset token.

 ```
 python3.9 test_api.py 
 ```
 


 ## API examples
 You can find in *tests* and *app* directories.
 A snippet here below:

 ```
 from py_jsm_asset  import RestAssetCommunicator
import json
Tester=RestAssetCommunicator("https://servicedesk.infn.it/rest/",Put Your Token,"1.0","LNFMAC")
answer=Tester.GetIcon(133)
print(json.dumps(answer))

 ```

## Applications



### csv_import.py

This application import a csv file into a preesistent type.
example of remapping, in the following case *Num Inventario* is duplicated as *Inventory* and *Name* (it's a system key that must be always present)

```

app/csv_import.py -t Inventory -i token.txt -d ";" -c app/inventario.csv -v -s "LNF Divisione Acceleratori"

or simply with configuration file :
app/csv_import.py --conf <myconfig>.json
```

and *<< myconfig >>.json*:

```

{
    "dest": "Inventory",
    "src": "app/inventario.csv",
    "token": "",
    "schema": "LNF Divisione Acceleratori",
    "delimiter": ";",
    "token":"MY API TOKEN",
    "mapping": {
        "Num Inventario": [ <<-- put the Num Inventario both on 'Name' and in 'Inventory'
            "Inventory",
            "Name"
        ],
        "Utilizzatore": "Owner",
        "Ruolo": "Ruolo",
        "Fornitore": "Fornitore",
        "Classe": "Classe",
        "Descrizione": "Descrizione",
        "Ub. Migr.": "Ub Migr",
        "Ubicazione": "Ubicazione",
        "Ubicazione Descr.": "Ubicazione Descr",
        "Tipo Bene": "Tipo Bene",
        "BP": "BP",
        "N. Nota": "Nota",
        "Anno Nota": "Anno Nota",
        "Valore Originario": "Valore Originario",
        "Decremento": "Decremento",
        "Incremento": "Incremento",
        "Valore Realizzo": "Valore Realizzo"
    },
    "filter" : []
}
```
 ### dhcp_import.py
 This application imports DHCP configuration file (__dhcp.conf__) into an existing __object type__ (let's call _TestDHCP_) with predefined __attribute__.
 The following attributes must be present in _TestDHCP_
 - **hostname** the DHCP _host_ entry
 - **mac** the DHCP  _hardware ethernet_ entry
 - **ip** the DHCP _fixed-addres_ entry
 - **router** the DHCP _option routers_ entry
 - **serverip** the DHCP _server-identifier_ entry
 - **nserver** the DHCP _next-server_ entry
 - **filename** the DHCP _filename_ entry

 The application will insert new entry if not existent or will update if existent. The application can generate an equivalent CSV list.
 A **token** file must be present with a preallocated API key with WRITE/READ capabilities.

 A command line example:

 ```
 python3.9 app/dhcp_import.py -c dhcpd.conf -s "LNF Divisione Acceleratori" -t "TestDHCP" -i token.txt 
 ```
#### Further import operators example in configuration

In *app/example-conf* there are real examples of operators use.

##### regexp operator
to include in the import just matching key value add to the json config:

*will include just CSV that have a Column 'Ref.  code' = 'VAC'*


```
"regexp":{
        "Ref. code":"VAC"

    }

```
##### matchgen operator
will match a list of key and replace a value (or subvalue)
```
will match the key 'Name' against the regexp 'match' and put the regexp group as value of the attribute 'Type'. This function is useful to extract from a string some pattern.

    "matchgen":[{"src":"Name","match":".+(VGC|VPC).+","dst":"Type"},
    {"src":"Name","match":".+VAC-([A-Z]{3,}).+","dst":"Type"},
    {"src":"Name","match":".+VAC-.*IONP\\d+$","then":"IONP","dst":"Type"} <-- just set IONP if match
    {"src":"Name","match":".+[:-](\\w+)$","dst":"NameIndexed","postfix":"-CAB","counter":0,"digit":3}
    ]

    src: is the the source CSV column
    dst: is the destination attribute
    postfix: append a string (optional)
    counter: append an incrementing number starting from  (optional)
    digit: number of digit (optional)
```
##### autoincrement operator
To append a numeric sequence to a `src` and create new values

```
    "autoincrement":[{"src":"Module","relcounter":true,"separator":"-","dst":"Name","counter":0,"step":1,"digit":3}]

    src: is the the source CSV column
    relcounter:true|false  (il relcounter the counter will restart each time the value will change)
    separator: separator between value and counter
    dst: is the destination attribute
    counter:0 start from 0 (optional)
    step: increment (optional)
    digit: number of digits (optional)

```
##### chain operator
To concatenate previous and/or next row, the following example will put previous 'Equipment Name' into 'Previous Element' and 'Next Element'
```
    "chain":[{"prev":"Equipment Name","dst":"Previous Element"},{"next":"Equipment Name","dst":"Next Element"}]

    prev/next: source column name
    dst: destination attribute




```
##### appendgen operator
To concatenate a list of column into a single attribute with a given separator
```
    "appendgen":[{"src":["SISTEMA","IOC"],"separator":"\n\r","dst":"Description"}],

    src: list of columns
    separator: separator applied
    dst: destination attribute

```
### aql_object_dump.py

Perform a search and dump of asset objects in _json_ and _csv_ (this case the keys to dump must be provided) formats.

Links and object references are still not handled

```
python3.9 app/aql_object_dump.py -t TestDHCP -d "Key,Name,mac" -i token.txt --aql "label LIKE pldante" -j dump.json -c dump.csv -v -s "LNF Divisione Acceleratori" 
```


 ### aql_object_delete.py

Starting from an _aql query_  the application delete objects of a given type (_-t_) in a given schema (_-s_)

A command line example:
```
## cancel all the object matching _alim*_ of the type _TestDHCP_ in the schema _LNF Divisione Acceleratori_
python3.9 app/aql_object_delete.py  -s "LNF Divisione Acceleratori" -t "TestDHCP" -i token.txt --aql "label LIKE alim" -v

```

 ### create_cross_references.py
 This application create a cross reference between object types, let's call source type and destination type. The relation is triggered by a common attribute name. For example if we have to types that have a *MAC* attribute defined and the MAC is identical in two objects beloging respectively to a *source type* and a *destination type* a relation between this two objects can be created by this application in a thierd attribute devoted to host the relation.
 Here below an example that search for identical *MAC* in the objects of type *"DHCP Nodes"* (source type) and object of type *"ADC"* (destination type) if the match is found a reference of the source object *"DHCP Nodes"* is created in the attribute *"SW Configuration"* of the destination type (*ADC*).

```
 python3.9 app/create_cross_references.py -st "DHCP Nodes -dt ADC -i token.txt -s "LNF Divisione Acceleratori" -a MAC -l "SW Configuration"

```


## License
For open source projects, say how it is licensed.