API

Installation

The traveler API can by found on pypi repository.. It can be installed using pip with the following command.

pip install Traveler-API

Getting API Key

Users can now request API key from the profile page on the traveler web application. This can be done by clicking on your name in the upper right corner and clicking profile in the drop down. Once on the profile page you should see a button that says "Generate API Key". If the button is not there contact your administrator to be given the API permission.

Initializing the API

Now that you have the API Key you can initialize the API and start querying the traveler system. The API Key will allow most read only calls and only some write commands. The other commands are reserved for higher level system accounts.

from traveler_api_factory import TravelerApiFactory

traveler_host = 'https://traveler.aps.anl.gov'
traveler_user = 'user'
traveler_api_key = '1234ApiKey'

factory = TravelerApiFactory(traveler_host, traveler_user, traveler_api_key)

Updating the traveler data using the API

This is one write calls that is possible to do using the API Key. It will allow updating traveler entries using the API. This feature allows automation of entering data however with great power comes great responsibility. The submission of travelers will still be a manual process, please review the traveler when submitting it to ensure that appropriate data was entered into the system.

See example below.

from travelerApi.models.traveler_data_options import TravelerDataOptions

traveler_api = factory.get_traveler_api()

traveler_id = '624dfcb76dfbee55357d3197'
traveler = traveler_api.get_traveler_by_id(traveler_id)

# See next section for getting input names instructions. Mapper will be some sample input names with values 

# The traveler can have various input types, see examples below with some sample data. 
mapper = {
    # Checkbox 
    'd13e0b98' : True,
    # Radio Button with Valid Value
    '67ef5695' : 'radio_text_1',
    # Number Input
    'fdab9c01' : 123,
    # Date Time Input
    'bf332394': '2020-12-31T13:32',
    # Date Input
    '94c548b6': '2022-04-06',
    # Time Input
    '00648737': '17:43',
    # URL Input
    '4b027304': 'https://anl.gov',
    # Text Input
    '9dd6d60f': 'Some Text',
    # Phone number Input
    '192bc68c': '630-152-5848',
    # Email Input
    'b85a6fd7': '[email protected]'    
}

# Update the traveler using the input names and values
for input_name in mapper.keys():
    input_value = mapper[input_name]
    dataOpts = TravelerDataOptions(name=input_name, value=input_value)
    result = traveler_api.update_traveler_data(traveler_id, dataOpts)

# Upload a file to a file upload input
file_upload_input_name = "d5fda46a"
file_upload_file_path = "/file/path/notes.txt"
upload_result = traveler_api.update_traveler_data_upload(traveler_id, name=file_upload_input_name, file_name=file_upload_file_path)

Getting the input names

Here are some ways I recommend fetching the names of the input in the traveler.

1. By fetching it out of the User defined key. However will not always work if the user defined keys were not specified during form design.

mapping = traveler.mapping
udk_info = "Input Name: %s \nUser Defined Key:%s"
for udk in mapping.keys():
    print(udk_info % (mapping[udk], udk))

2. By fetching it out of the labels. This can sometimes be helpful if the labels are meaningful enough.

labels = traveler.labels

label_info = "Input Name: %s \nLabel:%s"
for label in labels.keys():
    print(label_info % (label, labels[label]))

3. By using the web browser developer tools inspect tool. The name is the attribute the is needed for the script to work. See examples below.

<input type="checkbox" data-userkey="" name="d13e0b98">
<input type="radio" value="radio_text_1" name="67ef5695" data-userkey="">

NOTE: These names will be the same between traveler instances unless the input was removed and re-created on the form and you have traveler instances of different versions.

Downloading Files using API

Below are instructions to get started with downloading files from eTraveler using API. By default the files are downloaded into a systems temp directory. On Linux systems that is /tmp/. This can be changed by providing optional parameter when initializing api factory: TravelerApiFactory(download_directory='/some/path/for/files')

from travelerApi.models.traveler_data_options import TravelerDataOptions

traveler_api = factory.get_traveler_api()
data_api = factory.get_data_api()

traveler_id = '64de164c55ce505b0dd76f56'

datas = traveler_api.get_traveler_data_by_traveler_id(traveler_id)

for data in datas:
    data_id = data.id
    if data.input_type == 'file':        
        file_data = data_api.get_data_by_id(data_id)
        tmp_file_path = data_api.get_file_by_data_id(data_id)
        # Path of downloaded file
        print(tmp_file_path)
        # Metadata about the file upload
        print(file_data)