Follow

API Overview

API Overview

The API system helps a system administrator export and import data to the WorkLoud web application with an automated process, rather than manually make changes. 

The system is designed to have the ability to integrate with any system utilizing a web service-based API. The API sends and receives data in XML format.  Data from any system can be imported into WorkLoud using this format.  The API can also be used to retrieve data from WorkLoud for reporting or for use in other systems.  There is also a Microsoft Excel Add-In that enables importing and exporting tabular spreadsheet data directly from within Excel.  The API covers many WorkLoud data elements that are typically part of integrations but can also be expanded to cover any data element in WorkLoud. 

APIIntro.png

Authentication

In order to use the API, the user or process must first be authenticated.  In order to authenticate with the API, use the method described below.  The request data is a JSON object with username and password fields.  The response will be JSON object containing details about the login operation.  For successful logins, the “_r” field will be 1, and the “SessionID” field will contain a key that will be used in subsequent API calls to identify the user.

APIAuthentication.png

 

Accessible Data

The account (service or user) that is leveraged requires Organizational Units to be setup in the User Icon setting per the template in use. 

Recommendation:  Do not share accounts if interfaces need to be run at the same time and/or if they require different user icon settings.

APIAccessibledata.png

 

External Systems & Mapping

External systems represent mapping tables that translate incoming data fields from an external system to internal values, and outgoing internal values to the original external system values.  Some notable cases where this is useful are internal/external ID mapping, and code mappings.  For example, an external job code can be mapped to an internal job record in the system.  The system supports multiple external systems each with associated mapping tables.  You can specify the external system to use when importing and exporting.

 

Options

The following is the format and list of options that can be specified for an import or export.  The options element is placed inside the import or export elements in the formatted XML.  Placement of options is illustrated in the Import and Export Dictionaries.

Options.png

Setting

Description

Values

Mapping

The field attribute specifies the name of a field for which the supplied value will be translated with a mapping table specified by the ExternalSystem setting.  Multiple mappings can be listed.

The name of a field in the import or export

ExternalSystem

The value attribute specifies the name of the external system through which mappings will be applied.

The name of the external system to use.

SetActiveOrganizationalUnits

The value attribute is set to true or false.  If true, the system will use context information from previous user logins to fill in data to imports.

True or false

 

ID Mapping

In addition to field mapping, record ID values can also be mapped for references in the system and references in external systems.  To specify mapped values for record IDs, use the following XML syntax when importing the record.

IDMapping.png

 

Export Filtering

When exporting, export filters can be specified for the data to limit the amount of data returned.  To specify filters, use the following XML format.  There are export examples in the Appendix which further illustrate this capability.

exportfiltering.png

 

Importing Data

Importing data is achieved by posting the data to be imported in XML form to the import handler of the API.  The example below demonstrates how this is done.

importingdata.png

 

Exporting Data

Exporting data is achieved by sending a POST request to the export handler with the query for the data you want to retrieve.

exporting.png

 

Templates

All available import and export templates are available within the Workloud application via the Command Line Client link located in Tools.

 
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk