REST API: Guide for Implementers

Transcription

1 REST API: Guide for Implementers Version 1.03 SP-API-REST-IG R001.03

2 Sage 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 R Sage

3 Contents 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

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

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 address for the user to be assigned to the interface. You will need access to the s 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

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 The 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 Callback URL Checkbox. Check to display the other API fields. Not used, but you must enter a string using valid URL syntax. For example: 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. Sage

7 Create a Connected App Related Guides 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 connected app. Sage

8 Create a Connected App Related Guides 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 a temporary 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 flow related 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 the Permitted Users field to Admin approved users are pre-authorized: 11. Select Save. Sage People redisplays the Connected App Detail page. Sage

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 - this section uses the Fairsail Team Member profile - 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 the Fairsail Team Member profile. 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 All other fields Visible checked. Default selected. Unchecked. Connected App Access The newly created Connected App Checked. Tab Settings All selectable tabs Default Off Administrative Permissions API Enabled Api Only User View Setup and Configuration All other selectable fields Checked Leave unchecked until after you have created the User and reset the Security Token (see page 11). Checked Unchecked. Sage

10 Create a User Profile Related Guides 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 All other objects Read checked. View All checked 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

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 First Name Last Name Alias Username Nickname User License Profile Active Description Enter: test Enter: remote Automatically created by Sage People. Enter: testremote@support.fairsail.com 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 address. Automatically created by Sage People. Select Salesforce Select the newly created Profile, for example: Remote Access 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 to the user's address, confirming the User Name and including a log in link. 5. Select the log in link in the welcome , enter a password and complete the security question for the new user, then select Save. Sage People logs you in and displays an initial Profile page. Sage

12 Create a User Related Guides 6. Select the Administration link in the Profile page and go to Setup > Personal Setup > My Personal Information > Reset My Security Token. Sage People displays the Reset Security Token page: 7. Select Reset Security Token. Sage People sends an containing the new Security Token to the user's address. You must use the Security Token when testing the REST API setup - retain the or copy the Security Token to a temporary text file. 8. Reopen the dedicated User Profile for this user, go to the Administrative Permissions section and check Api Only User. 9. Select Save on the Profile. Sage

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/. You also need: curl is an open source tool and is not supported by Sage People. The Consumer Key and Consumer Secret generated when you created the Connected App for the REST API. 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 ID from the URL: Copy the ID to a temporary text file for later use. 4. Open a command prompt and enter: curl -k -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 eu3 o The access token. Sage

14 Test the Configuration Related Guides 6. At the command prompt enter: curl -k team_member c/a0yw boFEAQ -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 example response you would enter: curl returns a response of the form: Sage

15 Test the Configuration Related Guides 7. Now test that the user has access to Team Member data. The Team Member object is the only object to which the REST API user has access, as determined by the User Profile (see page 9). At the command prompt enter: curl -k s/fhcm2 team_member c/team_member_record_id -H "Authorization: Bearer ACCESS_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: Sage

16 Test the Configuration Related Guides 8. To confirm that access to other objects is locked, send a request for Employment Record data. At the command prompt enter: curl -k s/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

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 Sage