resource center   >  topics  >  Admin Set Up

Implementing Stracl REST API to Load and Update Org Data

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, that includes five 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

Attribute Type Max Length Required Attribute
Employee ID string 20 Required | Unique
Last_Name string 50 Required
First_Name string 50 Required
Title string 125 Optional
Email string 255 Optional
Login ID string 20 Optional
Country string 125 Optional
Location string 125 Optional
Level1_Mgr_ID string 20 Optional
Level1_Mgr string 125 Optional
Approving_Mgr_ID string 20 Optional
Custom_Field_1 string 125 Optional
Custom_Field_2 string 125 Optional
Custom_Field_3 string 125 Optional
Custom_Field_4 string 125 Optional
Custom_Field_5 string 125 Optional
Custom_Field_6 string 125 Optional
Custom_Field_7 string 125 Optional
Status_Code string 1 Optional

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.

Figure 2: Org Custom Fields 1 - 7 mapped in Stracl

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

Code Description
200 - OK Everything worked as expected
400 - Bad Request Missing/invalid parameters
401 - Unauthorized No valid API key provided
500 - Server Error Something went wrong on Stracl's end

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

Code Description
Missing_Attribute A required attribute is missing
string_value_exceeds_max_length A string value exceeds the max length. See employee object table above for the max limits.
wrong_data_type A value has the wrong data type. See employee object table above

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

Figure 3. REST API versus Manual Upload Process

Join The Organizational Change Management Software Revolution Today

Schedule Demo