1 Simphony Import/Export API

Import/Export API Prerequisites

  • Simphony version 2.8 or later is required.

  • Obtain Enterprise Management Console (EMC) credentials to access the web service.

  • You must have the privileges to access the database and run the Simphony Import/Export web service.

  • In order to use the web service, you must have a web client infrastructure. For example, Microsoft .NET Framework offers the WebClient class that can be used to make web service requests. Other programming languages and libraries can also be used to create a web client to use the Import/Export web service.

Mandatory Columns

Prior to developing your API, review the Import/Export Help for more information regarding mandatory columns for object types. To view the mandatory columns:

  1. Log in to Simphony.

  2. Click Import/Export, and then click Help.

  3. In theObject Info section, expand an object type to view the mandatory columns for that object type.

Security Service API

In order to use the Import/Export web service you must authenticate using valid EMC credentials. The security service API must be called first to obtain an authentication token. The other APIs of the web service can only be used if you have a valid authentication token. The Import/Export API token has a lifespan of 10 minutes. If there is no interaction with the API for 10 consecutive minutes, the token expires and re-authentication is required to obtain a new one.

To view the security service methods, enter the following URL in a web browser:

https://<home>/ImportExportAPI/SecurityService.svc/web/help

You can then view a table of methods, similar to the following table.

Table 1-1 Security Service Operations

URI Method Description

/GetUserAuthenticationToken

POST

Authenticates user and returns a token

/SignOffToken

POST

Invalidates the valid token

/GenerateOneTimeCode

POST

Generates one time passcode

/ValidateToken

POST

Validates token for user at a given org

GetUserAuthenticationToken

Description: Authenticates a user and returns a token.

URL: https://<home>/ImportExportAPI/SecurityService.svc/web/GetUserAuthenticationToken

HTTP Method: POST

Request JSON Body:

{

"orgCode":"String content",

"password":"String content",

"userName":"String content"

}

When using this web service request, you must replace the String content with valid Simphony credentials.

Response JSON Body:

"token"

With valid Simphony credentials, the web service responds with an authentication token. You need this token to successfully use the methods of the data service API, which are explained in the next section.

SignOffToken

Description: Invalidates the valid token.

URL: https://<home>/ImportExportAPI/SecurityService.svc/web/SignOffToken

HTTP Method: POST

Request JSON Body:

"String content"

When using this web service request, you must replace the String content with a valid authentication token that should be signed off.

GenerateOneTimeCode

Description: Generates one time passcode.

URL: https://<home>/ImportExportAPI/SecurityService.svc/web/GenerateOneTimeCode

HTTP Method: POST

Request JSON Body:

{

"orgCode":"String content",

"password":"String content",

"userName":"String content"

}

When using this web service request, you must replace the String content with valid Simphony credentials.

Response JSON Body:

“String Content”

With valid Simphony credentials, the web service generates OTP and dispatches it to the user’s registered email address. This OTP is used for Multi-factor Authentication (MFA). This webservice is used by the Egateway or system in case of MFA.

ValidateToken

Description: Validates token for user at a given org.

URL: https://<home>/ImportExportAPI/SecurityService.svc/web/ValidateToken

HTTP Method: POST

Request JSON Body:

{

"orgCode":"String content",

"password":"String content",

"userName":"String content"

}

When using this web service request, you must replace the String content with valid Simphony credentials.

Response JSON Body:

With valid Simphony credentials, the web service validates OTP available in the headers and returns whether it is True or False.

Data Service API

The data service API provides the core functionality of the Import/Export web service. The methods of the data service are listed in the following table.

To view detailed descriptions of the data service methods, enter the following URL in a web browser:

https://<home>/ImportExportAPI/DataService.svc/web/help

The orgCode is needed in a multi-tenant context.

Table 1-2 Data Service Operations

URI Method Description

/AddSchedule

POST

Adds a new schedule. Returns positive schedule Id if successful, otherwise returns -1.

/GetBuildVersion

GET

Returns the Build version of API.

/GetExportableTypes/{userName}/{*orgCode}

GET

Returns the type of objects exportable from this service.

/GetFileData/{requestId}/{userName}/{*orgCode}

GET

Returns the file bytes for a given export request, or an error file if an error occurs.

/GetHierarchyStructure/{userName}/{*orgCode}

GET

Returns all Hierarchy objects (Enterprise, Properties, RVC's, and Zones) available for the current user in a given organization.

/GetImportableTypes/{userName}/{*orgCode}

GET

Returns the type of objects importable from this service.

/GetObjectInfo/{userName}/{*orgCode}

GET

Help Info: returns object information.

/GetPropertiesForType/{fullyQualifiedTypeName}/{userName}/{*orgCode}

GET

Returns the attributes (Columns) of objects available on a given object.

/GetRequests/{days}/{userName}/{*orgCode}

GET

Returns all requests made by this user’s org for specified up to 30 days with latest status. Includes originally scheduled active requests.

/GetRequestStatus/{requestId}/{userName}/{*orgCode}

GET

Returns the request object with latest status.

/GetSchedules/{userName}/{*orgCode}

GET

Returns all schedules available in this organization.

/GetServerTimeWithZone

GET

Returns server current time and time zone.

/GetSnapShotBeforeImport/{requestId}/{userName}/{*orgCode}

GET

Returns the original snap-shot of backed up data in bytes before the given import is processed.

/GetSupportedLanguages/{userName}/{*orgCode}

GET

Returns all the Simphony configured languages for a given organization.

/SubmitImportExportRequest

POST

Submit a request for Import or Export.

/UpdateRequestStatus

POST

Updates the status of a request, enabling it to be cancelled.

/UpdateScheduleStatus

POST

Enables or disables a schedule.

/GetEmployeeLanguageId

POST

Returns the LanguageID of a given user.

AddSchedule

Description: Adds a new schedule. Returns positive schedule Id if successful, otherwise returns -1.

URL: https://<home>/ImportExportAPI/DataService.svc/web/AddSchedule

HTTP Method: POST

Request JSON Body:

{

"Active":true,

"DaysOfMonth":[2147483647],

"Friday":true,

"Id":9223372036854775807,

"Monday":true,

"Name":"String content",

"OrgCode":"String content",

"Saturday":true,

"StartDate":"\/Date(928167600000-0500)\/",

"Sunday":true,

"Thursday":true,

"TimeOfDay":"\/Date(928167600000-0500)\/",

"Tuesday":true,

"UserName":"String content",

"Wednesday":true

}

Response JSON Body:

9223372036854775807

GetBuildVersion

Description: Returns the Build version of API.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetBuildVersion

HTTP Method: GET

Response JSON Body:

["String content"]

GetExportableTypes

Description: Returns the type of objects exportable from this service.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetExportableTypes/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

["String content"]

GetFileData

Description: Returns the file bytes for a given export request, or an error file if an error occurs.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetFileData/{REQUESTID}/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[81,

109,

70,

122,

90,

83,

65,

50,

78,

67,

66,

84,

100,

72,

74,

108,

89,

87,

48,

61]

GetHierarchyStructure

Description: Returns all Hierarchy objects (Enterprise, Properties, RVC's, and Zones) available for the current user in a given organization.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetHierarchyStructure/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[{

"HierarchyId":9223372036854775807,

"Id":9223372036854775807,

"ObjectNumber":2147483647,

"HierarchyName":[{

"LangId":2147483647,

"Text":"String content"

}],

"OrganizationId":2147483647,

"ParentHierarchyId":9223372036854775807,

"UnitType":0

}]

GetImportableTypes

Description: Returns the type of objects importable from this service.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetImportableTypes/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

["String content"]

GetObjectInfo

Description Returns Object Information.

URL: https://<home> /ImportExportAPI/DataService.svc/web/GetObjectInfo/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[{

"ColumnInfo":[{

"AllowNullsOnImport":"String content",

"AlternateColumnType":"String content",

"ColumnName":"String content",

"ColumnType":"String content",

"DefaultValue":"String content",

"ExportOnly":true,

"KeyColumn":true

}],

"Exportable":true,

"FullTypeName":"String content",

"Importable":true,

"ShortName":"String content"

}]

GetPropertiesForType

Description: Returns the attributes (Columns) of objects available on a given object.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetPropertiesForType/{FULLYQUALIFIEDTYPENAME}/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

["String content"]

GetRequests

Description: Returns all requests made by this user’s org for specified up to 30 days with latest status. Includes originally scheduled active requests.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetRequests/{DAYS}/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[{

"DataForImport":[81,

109,

70,

122,

90,

83,

65,

50,

78,

67,

66,

84,

100,

72,

74,

108,

89,

87,

48,

61],

"DataSince":"\/Date(928167600000-0500)\/",

"HierStrucId":9223372036854775807,

"HierStrucIds":"String content",

"LanguageId":2147483647,

"Level":0,

"ObjectNumberFilter":"String content",

"ObjectType":"String content",

"OrgCode":"String content",

"Origin":0,

"OriginalRequestId":9223372036854775807,

"RequestDate":"\/Date(928167600000-0500)\/",

"RequestId":9223372036854775807,

"RequestName":"String content",

"ScheduleId":9223372036854775807,

"SelectedFormat":0,

"SelectedObjectMembers":["String content"],

"SelectedOperation":0,

"SortExpressions":[{

"m_Item1":"String content",

"m_Item2":"String content"

}],

"Status":0,

"UserName":"String content"

}]

GetRequestStatus

Description: Returns the request object with latest status.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetRequestStatus/{REQUESTID}/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

{

"DataForImport":[81,

109,

70,

122,

90,

83,

65,

50,

78,

67,

66,

84,

100,

72,

74,

108,

89,

87,

48,

61],

"DataSince":"\/Date(928167600000-0500)\/",

"HierStrucId":9223372036854775807,

"HierStrucIds":"String content",

"LanguageId":2147483647,

"Level":0,

"ObjectNumberFilter":"String content",

"ObjectType":"String content",

"OrgCode":"String content",

"Origin":0,

"OriginalRequestId":9223372036854775807,

"RequestDate":"\/Date(928167600000-0500)\/",

"RequestId":9223372036854775807,

"RequestName":"String content",

"ScheduleId":9223372036854775807,

"SelectedFormat":0,

"SelectedObjectMembers":["String content"],

"SelectedOperation":0,

"SortExpressions":[{

"m_Item1":"String content",

"m_Item2":"String content"

}],

"Status":0,

"UserName":"String content"

}

GetSchedules

Description: Returns all schedules available in this organization.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetSchedules/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[{

"Active":true,

"DaysOfMonth":[2147483647],

"Friday":true,

"Id":9223372036854775807,

"Monday":true,

"Name":"String content",

"OrgCode":"String content",

"Saturday":true,

"StartDate":"\/Date(928167600000-0500)\/",

"Sunday":true,

"Thursday":true,

"TimeOfDay":"\/Date(928167600000-0500)\/",

"Tuesday":true,

"UserName":"String content",

"Wednesday":true

}]

GetServerTimeWithZone

Description: Returns server current time and time zone.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetServerTimeWithZone

HTTP Method: GET

Response JSON Body:

["String content"]

GetSnapShotBeforeImport

Description: Returns the original snap-shot of backed up data in bytes before the given import is processed.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetSnapShotBeforeImport/{REQUESTID}/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[81,

109,

70,

122,

90,

83,

65,

50,

78,

67,

66,

84,

100,

72,

74,

108,

89,

87,

48,

61]

GetSupportedLanguages

Description: Returns all Simphony configured languages for a given organization.

URL: https://<home>/ImportExportAPI/DataService.svc/web/GetSupportedLanguages/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

[{

"HierarchyId":9223372036854775807,

"Id":9223372036854775807,

"ObjectNumber":2147483647,

"LanguageName":[{

"LangId":2147483647,

"Text":"String content"

}]

}]

SubmitImportExportRequest

Description: Submit a request for Import or Export.

URL: https://<home>/ImportExportAPI/DataService.svc/web/SubmitImportExportRequest

HTTP Method: POST

ObjectNumberFilter is an optional parameter you can specify to export a specific range of objects. The ObjectNumberFilter parameter is a string in the format 1-200,230,300-350,..

The following sample JSON request shows the ObjectNumberFilter parameter.

Request JSON Body:

{

"DataForImport":[81,

109,

70,

122,

90,

83,

65,

50,

78,

67,

66,

84,

100,

72,

74,

108,

89,

87,

48,

61],

"DataSince":"\/Date(928167600000-0500)\/",

"HierStrucId":9223372036854775807,

"HierStrucIds":"String content",

"LanguageId":2147483647,

"Level":0,

"ObjectNumberFilter":"String content",

"ObjectType":"String content",

"OrgCode":"String content",

"Origin":0,

"OriginalRequestId":9223372036854775807,

"RequestDate":"\/Date(928167600000-0500)\/",

"RequestId":9223372036854775807,

"RequestName":"String content",

"ScheduleId":9223372036854775807,

"SelectedFormat":0,

"SelectedObjectMembers":["String content"],

"SelectedOperation":0,

"SortExpressions":[{

"m_Item1":"String content",

"m_Item2":"String content"

}],

"Status":0,

"UserName":"String content"

}

Response JSON Body:

{

"RequestId":9223372036854775807,

"Status":0

}

UpdateRequestStatus

Description: Updates the status of a request enabling it to be cancelled.

URL: https://<home>/ImportExportAPI/DataService.svc/web/UpdateRequestStatus

HTTP Method: POST

Request JSON Body:

{

"OrgCode":"String content",

"RequestId":2147483647,

"RequestStatus":0,

"UserName":"String content"

}

Response JSON Body:

["String content"]

UpdateScheduleStatus

Description: Enables or disables a schedule.

URL: https://<home>/ImportExportAPI/DataService.svc/web/UpdateScheduleStatus

HTTP Method: POST

Request JSON Body:

{

"Active":true,

"DaysOfMonth":[2147483647],

"Friday":true,

"Id":9223372036854775807,

"Monday":true,

"Name":"String content",

"OrgCode":"String content",

"Saturday":true,

"StartDate":"\/Date(928167600000-0500)\/",

"Sunday":true,

"Thursday":true,

"TimeOfDay":"\/Date(928167600000-0500)\/",

"Tuesday":true,

"UserName":"String content",

"Wednesday":true

}

GetEmployeeLanguageId

Description: Returns the LanguageID of a given user.

URL: https://<home>/ImportExportAPI/DataService.svc/web/ GetEmployeeLanguageId/{USERNAME}/{ORGCODE}

HTTP Method: GET

Response JSON Body:

The language id is returned

9223372036

Download Service API

DownloadService API enables the user to download the following binaries:
  • CAL client for Windows
  • CAL client for Android
  • Enterprise Management Console (EMC)

It also provides API methods used by EMC for the self-updates.

To view the Download Service methods, enter the following URL in a web browser:

https://<home>/ImportExportAPI/DownloadService.svc/web/help, in order

You can then view a table of methods, similar to the following table.

Table 1-3 Download Service Operations

URI Method Description

/GetZipEMCClientFiles

POST

Accepts EMC file names in the request body and returns a Stream containing a zip of all requested EMC files.

/GetEMCManifest

GET

Returns a Stream containing contents of EMC Manifest file.

/GetBinaries

GET

Accepts the type of download to be performed and returns bytes containing contents of the downloaded file.

/GetSelfUpdateVersion

GET

Returns the current version of the self-update download mechanism.

GetZipEMCClientFiles

Description: Accepts EMC file names in the request body and returns a Stream containing a zip of all requested EMC files.

URL: https://<home>/ImportExportAPI/ DownloadService.svc/web/GetZipEMCClientFiles/{USERNAME}/{ORGCODE}

HTTP Method: POST

Request JSON Body:

The Request body is empty.

Response JSON Body:

The Response body is a byte stream.

GetEMCManifest

Description: Returns a Stream containing contents of EMC Manifest file.

URL: https://<home>/ImportExportAPI/ DownloadService.svc/web/GetEMCManifest/{USERNAME}/{ORGCODE}

HTTP Method: GET

Request JSON Body:

The Request body is empty.

Response JSON Body:

The Response body is a byte stream.

GetBinaries

Description: Accepts the type of download to be performed and returns bytes containing contents of the downloaded file.

URL: https://<home>/ImportExportAPI/ DownloadService.svc/web/GetBinaries/{USERNAME}/{DOWNLOADTYPE}/{ORGCODE}

HTTP Method: GET

Request JSON Body:

The Request body is empty.

Response JSON Body:

[81,

109,

70,

122,

74,

108,

89,

87,

48,

61]

GetSelfUpdateVersion

Description: Returns the current version of the self-update download mechanism.

URL: https://<home>/ImportExportAPI/ DownloadService.svc/web/GetSelfUpdateVersion/{USERNAME}/{ORGCODE}

HTTP Method: GET

Request JSON Body:

The Request body is empty.

Response JSON Body:

The Response body is a byte stream.