Purpose

The purpose of this document is to explain how Stracl customers can import their org data using Stracl REST API. This document will explain the setup process, responsibilities, and skill sets needed to test the REST API implementation, and the time you will need to set up the service.

‍Overview

Stracl is a cloud-based software to automate and accelerate change management. It is primarily used by Change Management Professionals, Project Managers, Instructional Designers, and Security Specialists to do the following:

• Conduct Stakeholder Analysis 
• Analyze and Mitigate Change Impacts 
• Create and Manage Communication & Engagement Plans 
• Perform Training Design and Track Training Development 
• Map future-state roles to security access and required training 
• Analyze corporate Organizational Data to support your projects

As part of setting up Stracl, a company’s organizational employee data needs to be loaded into application, so the Stracl modules can access it.

Stracl uses representational state transfer (REST) for building APIs that allow end users to connect and interact with cloud services.

Org data that is loaded into Stracl is very basic: employee ID, name, email, manager name and manager’s email, and location data. No passwords, personal details, performance or salary details are ever loaded in Stracl. There is a total of sixteen org data fields, which includes seven custom fields, as illustrated by the figure below.

The REST API will allow you to build an application for importing org data from your own environment to Stracl. Once built, you can use the REST API to load org data and update it on a recurring basis that you set up. This will mean that Stracl is always working with the latest org data to support all the tasks it performs.The REST API will allow you to import data into Stracl from a remote environment.

Requirements  

• You or a programming resource must knowhow to write the code that sends your Org Data to the REST API. We will provide examples in the multiple programming languages that you can adapt to your database structure, to get you quickly up and running.
• You must use the API access key provided by Stracl for every request

Benefits

• Higher performance and an automated solution
• Improved user productivity: reduced errors, reduced training and faster updates
• Greater security for your Org Data than emailing and uploading spreadsheets from individual computers to Stracl
• Support for JSON and XML

Roles, Responsibilities and Time Requirements

Stracl

• A Stracl resource will provide you with setup guidance, access token, testing account and technical support.
• Estimated Time Requirements: 15 to 30 hours

Your Company

• Your company’s technical resource will write and test the import application. The example application provided can be modified quickly to work with your database structure.
• Estimated Time Requirements: 15 to 30 hours

Both the above time requirements are estimates.

For a customized quote, contact sales@stracl.com to set up a technical conversation between Stracl tech support and your technical resource.

‍REST API Technical Set-up

Stracl provides two methods to enable you to import and update Org Data:‍

‍1. Manual – Stracl Org Data Import ‍

This scenario you log into Stracl as an Administrator and load/import a formattedMicrosoft Excel file into Stracl.Validation will ensure that your file is formatted correctly, and a review page will enable you to view a report showing any rows that did not import correctly.

This scenario enables you to import your data any time you want but requires you to export your org data from your system into the formatted MS Excel file and to make sure the header row is correct before importing.

This scenario does not require the assistance of technical staff to write the code necessary to connect to and upload/import org data into Stracl.However, you will need your technical staff to set up an automated output file that can be imported into Stracl.

‍2. Automated/Programmatic -- Importing and Updating org data using the REST API

This scenario requires the assistance of technical staff to write code necessary to connect to the Stracl API. The technical staff would write code that connects to your database and queries for the org data you want to import to Stracl. Then, that data would be sent to the Stracl database using the API. The REST API will return the result of the import as well as any errors encountered during processing of the request.

Although this scenario requires the use of technical staff to write the solution, it also provides full automation of data flow between your database and the Stracl database. The end solution can be scheduled to take place at any time, allowing your data to be continuously synced with Stracl.

Setting Up and Using the REST API

Authentication

1. Basic Authentication: Stracl will provide you with a username and password.
2. API Key

Stracl will provide you with an API authentication key that should be present in the“Authorization” header in every request made to the API.

Making the import request in “JSON Array” format

To import employees in “JSON Array” format, you need to make a POST request(HTTPS) to https:\\apps.jtask.com\yourcompany\api\v1\import

If an employee with the same Employee_ID already exists, it will be updated, otherwise a new employee will be created. The HTTP request headers need to contain:

Content-Type: application/json
Authorization: xxxxxxxxxxxxxxxxxxxxxxxxx (in case of API Key)
Authorization: Basic xxxxxxxxxxxxxxxxx (in case of Basic Authentication)
X-Test-Mode: true

The request body should contain an array of employee objects, for example:

{
  "Employee_ID": "125",
  "First_Name": "John",
  "Last_Name": "Doe",
  "Title": "CEO",
  "Email": "johndoe@stracl.com",
  "Login_ID": "jdoe",
  "Country": "USA",
  "Location": "San Francisco",
  "Level1_Mgr_ID": "100",
  "Level1_Mgr": "Alex Wang",
  "Approving_Mgr_ID": "300",
  "Custom_Field_1": "Custom value",
  "Status_Code": "D"
},
… 

‍Making the import request in non standard JSON format

To import employees in nonstandard JSON format, you need to make a POST request(HTTPS) to https:\\apps.jtask.com\yourcompany\api\v1\importsf

Nonstandard JSON format means the employee objects are separated by a line break.

If an employee with the same Employee_ID already exists, it will be updated, otherwise a new employee will be created. The HTTP request headers need to contain:

Content-Type: application/json
Authorization: xxxxxxxxxxxxxxxxxxxxxxxxx (in case of API Key)
Authorization: Basic xxxxxxxxxxxxxxxxx (in case of Basic Authentication)
X-Test-Mode: true

The request body should be in the following format:

{
  "Employee_ID": "125",
  "First_Name": "John",
  "Last_Name": "Doe",
  "Title": "CEO",
  "Email": "johndoe@stracl.com"
}

{
  "Employee_ID": "126",
  "First_Name": "John",
  "Last_Name": "Doe Two",
  "Title": "Sales Manager",
  "Email": "johndoetwo@stracl.com"
}

{
  "Employee_ID": "127",
  "First_Name": "John",
  "Last_Name": "Doe Three",
  "Title": "CTO",
  "Email": "johndoethree@stracl.com"
}

{
  "Employee_ID": "128",
  "First_Name": "John",
  "Last_Name": "Doe Four",
  "Title": "CTO",
  "Email": "johndoefour@stracl.com"
}

Employee Object

Stracl REST API compares existing records in the Org table (based on the Employee ID) to those in the JSON data object that you sent over.  For all existing records in the Org table, all fields are updated.  For all new records found in the JSON data object that were not in the Org table, they are inserted into the Org table.  No Org records were removed.  To remove an Org record from Stracl, enter “D” in the Status_Codefield.

To see what information is mapped to the five “Custom Fields”, you need to log into Stracl and navigate to Admin Menu > Dynamic Labels.

Testing

To test your application and interact with the API without updating the Stracl database, you can add the following custom HTTP header to your request:

X-Test-Mode: true

Any request containing this header will go to the data validation process and send a normal response back. No changes will be made to the Stracl database!

Response

Stracl uses conventional HTTP response codes to indicate success or failure. If everything was okay and the employees were imported or updated, you will receive a response with the status code 200.

HTTP Status Code Summary

Trouble shooting Bad Request Error - 400

If your request contained missing or invalid parameters in your request, you will receive a response with a 400 status code and the import or update will not complete. The response body will contain an error object with details.

Detailed error types

The error object contains two main attributes:

• “errors”- a collection of all employee object attributes that contain an error, sorted by error code.
• “error_details” - a collection of each employee object with the errors that it contains.

Example:

{
  "errors": {
    "missing_attribute": ["First_Name", "Last_Name"],
    "string_value_exceeds_max_length": ["Employee_ID"],
    "wrong_data_type": ["Approving_Mgr_ID"]
  },
  "error_details": [{
    "Employee_ID": "125",
    "errors": {
      "missing_attribute": ["First_Name", "Last_Name"],
      "string_value_exceeds_max_length": ["Employee_ID"],
      "wrong_data_type": ["Approving_Mgr_ID"]
    }
  }]
}

Additional Help

Request for full import and update application example in C#

Stracl can provide you with a working application example in C#,that your programming resource can modify, to get up and running quickly. Please contact support@stracl.com.

Request for Active Directory import script example in PowerShell

Stracl can provide you with an Active Directory import script example in PowerShell, that your programming resource can modify, to get up and running quickly. Please contact support@stracl.com.

Appendix