SP-API-REST-IG-201907--R001.04

REST API: Guide for Implementers Version 1.04

© Sage 2019 2

© Sage 2019. All rights reserved.

This document contains information proprietary to Sage and may not be reproduced, disclosed, or used in whole or in part without the written permission of Sage.

Software, including but not limited to the code, user interface, structure, sequence, and organization, and documentation are protected by national copyright laws and international treaty provisions. This document is subject to U.S. and other national export regulations.

Sage takes care to ensure that the information in this document is accurate, but Sage does not guarantee the accuracy of the information or that use of the information will ensure correct and faultless operation of the service to which it relates. Sage, its agents and employees, shall not be held liable to or through any user for any loss or damage whatsoever resulting from reliance on the information contained in this document.

Nothing in this document alters the legal obligations, responsibilities or relationship between you and Sage as set out in the contract existing between us.

This document may contain screenshots captured from a standard Sage system populated with fictional characters and using licensed personal images. Any resemblance to real people is coincidental and unintended.

All trademarks and service marks mentioned in this document belong to their corresponding owners.

SP-API-REST-IG-201907--R001.04

Contents

© Sage 2019 3

Contents

About this Guide 4 Related Guides 4

Introduction 5

Create a Connected App 6

Create a User Profile 9

Create a User 11

Test the Configuration 13

Index 17

© Sage 2019 4

About this Guide This REST API Guide for Implementers provides step by step guidance for setting up a web service between a customer server and the Sage People database to enable REST API level access to Sage People hosted data.

Related Guides REST API: Guide for Developers Coverage summary

An introduction to the key characteristics and architecture of the Sage People REST API, using Sage People resources, and authentication.

Typical target audience

You have familiarity with the software development process, Web services, and the Salesforce user interface. You are providing developer-level support to a customer organization seeking to establish a web service interface between a customer server and the Sage People database to enable REST API level access to Sage People hosted data.

© Sage 2019 5

Introduction Before starting to set up the REST API interface, make sure that:

• You have administrator level access to the customer org.

• You have a valid contact email address for the user to be assigned to the interface. You will need access to the emails sent by the system as part of the configuration.

• You have the cURL command line tool installed. You use cURL to test the configuration. cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/.

cURL is an open source tool and is not supported by Sage People.

Screen shots in this guide are taken from a Sage People Supertrial and are indicative.

Now follow this sequence:

1. Create a new Connected App (see page 6).

2. Create a new User Profile to use the new Connected App (see page 9). The Profile ensures that access permissions are tightly restricted.

3. Create a new User linked to the User Profile (see page 11). This is the REST API user for accessing Sage People data.

4. Test the configuration (see page 13).

© Sage 2019 6

Create a Connected App A Connected App enables the external server to use the REST API to access Sage People data. The app uses standard authentication protocols and enables control over who can use it.

To create a Connected App for REST API use:

1. Go to Setup > App Setup > Create > Apps

2. In the Connected Apps Related List, select New.

Sage People displays the New Connected App page

3. Complete the fields as follows:

Field Description

Basic Information section

Connected App Name A name for the Connected App. Use a short, descriptive name, for example HCM Remote.

API Name Automatically created by Sage People based on the Connected App Name you entered.

Contact Email The email address of the User to be used for the interface.

Description A brief description of the App. For example: Connected App for REST API access

API (Enable OAuth Settings)

Enable OAuth Settings

Checkbox. Check to display the other API fields.

Callback URL Not used, but you must enter a string using valid URL syntax. For example: https://example.com/sagepeople/hcmremote

Use digital signatures Checkbox. Leave unchecked.

Selected OAuth Scopes

In the list of Available OAuth Scopes select Access and manage your data (api) and select

Add

Leave all other fields blank.

Create a Connected App

© Sage 2019 7

The completed page looks like this:

4. Select Save.

Sage People displays the message:

Allow from 2-10 minutes for your changes to take effect on the server before using the connectedapp.

Create a Connected App

© Sage 2019 8

5. Select Continue.

Sage People displays the Connected App Name page for the new App:

6. You need the Consumer Key and Consumer Secret when testing the configuration. Copy them to atemporary text file while this page is displayed.

7. While on the Connected App Name page, you can use the Trusted IP Range for OAuth Web server flowrelated list to specify a restricted set of IPs to use REST API access:

8. On the Connected App Name page, select Manage.

Sage People displays the Connected App Detail page.

9. On the Connected App Detail page select Edit.

Sage People displays the Connected App Edit page.

10. On the Connected App Edit page go to the OAuth policies section and use the pick list to change thePermitted Users field to Admin approved users are pre-authorized:

11. Select Save.

Sage People redisplays the Connected App Detail page.

© Sage 2019 9

Create a User Profile The user profile assigned to the REST API user must have restricted permissions. Base the profile on an existing profile with a Salesforce license type and remove most of the permissions.

To create a new profile:

1. Go to Setup > Administration Setup > Manage Users > Profiles

2. Select the Name for a Profile with User License set to Salesforce.

Sage People displays the Profile Detail page.

3. Select Clone to make a copy of the profile.

Sage People displays the Clone Profile page.

4. Enter a Profile Name, for example: Remote Access.

Sage People creates the new Profile and displays the Profile Detail page.

5. Select Edit.

Sage People displays the Profile Edit page.

6. Set the permissions and page layouts as follows:

Custom App Settings

Fairsail HCM Profile Only

Visible checked.Default selected.

All other fields Unchecked.

Connected App Access

The newly created Connected App

Checked.

Tab Settings

All selectable tabs Default Off

Administrative Permissions

API Enabled Checked

Api Only User Leave unchecked until after you have created the User and reset the Security Token (see page 11).

View Setup and Configuration

Checked

All other selectable fields

Unchecked.

Create a User Profile

© Sage 2019 10

General User Permissions

All fields Unchecked.

Standard Object Permissions

All objects Unchecked. Note: uncheck Read to automatically uncheck all other checkboxes for that object.

Custom Object Permissions

Team Members Read checked. View All checked

All other objects Unchecked. Note: uncheck Read to automatically uncheck all other checkboxes for that object.

Desktop Integration Clients

All fields Leave default values unchanged.

Session Timeout

Timeout value Leave default value unchanged.

Password Policies

All fields Leave default values unchanged.

7. Select Save.

Sage People saves the reworked profile and redisplays the Profile page.

© Sage 2019 11

Create a User The REST API user must be assigned to the restricted permission User Profile you have created (see page 9).

Do not use an existing user - create one specifically for REST API use.

To create a new user:

1. Go to Setup > Administration Setup > Manage Users > Users

Sage People displays the All Users page.

2. Select New User.

Sage People displays the New User, User Edit page.

3. Complete the fields as follows:

Field Description

First Name Enter: test

Last Name Enter: remote

Alias Automatically created by Sage People.

Email Enter: testremote@support.fairsail.com

Username Automatically created by Sage People. The Username must be unique across Salesforce. If there is a conflict with an existing Username, an error message is displayed when you save the New User. In case of a conflict, change the Username - it does not have to match the Email address.

Nickname Automatically created by Sage People.

User License Select Salesforce

Profile Select the newly created Profile, for example: Remote Access

Active Checked

Leave default values unchanged for all other fields.

4. Select Save.

Sage People saves the User definition and displays the User Detail page.

Sage People sends a welcome email to the user's email address, confirming the User Name and includinga log in link.

5. Select the log in link in the welcome email, enter a password and complete the security question for the newuser, then select Save.

Sage People logs you in and displays an initial Profile page.

Create a User

© Sage 2019 12

6. Select the Administration link in the Profile page and go to Setup > Personal Setup > My PersonalInformation > Reset My Security Token.

Sage People displays the Reset Security Token page:

7. Select Reset Security Token.

Sage People sends an email containing the new Security Token to the user's email address. You must usethe Security Token when testing the REST API setup - retain the email or copy the Security Token to atemporary text file.

8. Reopen the dedicated User Profile for this user, go to the Administrative Permissions section and checkApi Only User.

9. Select Save on the Profile.

© Sage 2019 13

Test the Configuration Before starting to test the configuration make sure that you have the cURL command line tool installed. cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/.

cURL is an open source tool and is not supported by Sage People.

You also need:

• The Consumer Key and Consumer Secret generated when you created the Connected App for the RESTAPI.

• The User Name, Password, and Security Token for the dedicated REST API User you created.

To test the configuration:

1. Login to Sage People using the User Name you created.

2. From the Profile page select the Administration link, display All Tabs and select the Team Members tab.

3. Select a Team Member to display the Team Member Detail page, and copy the Team Member record IDfrom the URL:

Copy the ID to a temporary text file for later use.

4. Open a command prompt and enter:

curl -k https://login.salesforce.com/services/oauth2/token -d "grant_type=password" -d"client_id=CONSUMER_KEY" -d "client_secret=CONSUMER_SECRET" -d"username=testremote@support.fairsail.com" -d "password=MYPASSWORDMYSECURITYTOKEN"

Where:o CONSUMER_KEY is the Consumer Key generated when you created the Connected App for the REST

API.o CONSUMER_SECRET is the Consumer Secret generated when you created the Connected App for the

REST API.o MYPASSWORDMYSECURITYTOKEN is the Password and Security Token combination for the

dedicated REST API User you created.

If you are connecting to a Sandbox replace login.salesforce.com in the host name with test.salesforce.com

cURL returns a response of the form:

5. From the response copy:o The server name from the instance url, in this case eu3o The access token.

Test the Configuration

© Sage 2019 14

6. At the command prompt enter:

curl -khttps://SERVER_NAME.salesforce.com/services/data/v20.0/sobjects/fhcm2__team_member__c/a0Yw00000098boFEAQ -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" -H"X-PrettyPrint:1"

Where SERVER_NAME and ACCESS_TOKEN are taken from the cURL response. Using the exampleresponse you would enter:

cURL returns a response of the form:

Test the Configuration

© Sage 2019 15

7. Now test that the user has access to Team Member data. The Team Member object is the only object towhich the REST API user has access, as determined by the User Profile (see page 9). At the commandprompt enter:

curl -k https://SERVER_NAME.salesforce.com/services/data/v20.0/sobjects/fhcm2__team_member__c/TEAM_MEMBER_RECORD_ID -H "Authorization: BearerACCESS_TOKEN" -H "Content-Type: application/json" -H "X-PrettyPrint:1"

Where:o SERVER_NAME and ACCESS_TOKEN are as used in the previous step.o TEAM_MEMBER_RECORD_ID is the one copied from the Team Member Detail page URL at the start

of this procedure.

cURL returns a response containing the data for the Team Member:

Test the Configuration

© Sage 2019 16

8. To confirm that access to other objects is locked, send a request for Employment Record data. At thecommand prompt enter:

curl -k https://SERVER_NAME.salesforce.com/services/data/v20.0/sobjects/fhcm2__employment__c -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type:application/json" -H "X-PrettyPrint:1"

Where:o SERVER_NAME and ACCESS_TOKEN are as used previously.

cURL returns an error:

© Sage 2019 17

Index A About this Guide • 4

C Create a Connected App • 5, 6 Create a User • 5, 9, 11 Create a User Profile • 5, 9, 11, 15

I Introduction • 5

R Related Guides • 4 REST API

Guide for Developers • 4

T Test the Configuration • 5, 13