Web Service Guide - RedCarpet - Login - SilkRoad Technology

Web Service GuideVersion 2014.3.0

SilkRoad technology, inc. PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OFMERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. In no event shall SilkRoad be liable for any lossof profits, loss of business, loss of use of data, interruption of business, or for indirect, special, incidental, or consequentialdamages of any kind, even if SilkRoad has been advised of the possibility of such damages arising from this publication.SilkRoad may revise this publication from time to time without notice. Some states or jurisdictions do not allow disclaimerof express or implied warranties in certain transactions; therefore, this statement may not apply to you.Copyright © 2012 SilkRoad technology, inc. All rights reserved.RedCarpet and Eprise are trademarks or registered trademarks of SilkRoad technology, inc. in the United States and othercountries.You may not download or otherwise export or reexport this Program, its Documentation, or any underlying information ortechnology except in full compliance with all United States and other applicable laws and regulations, including withoutlimitations the United States Export Administration Act, the Trading with the Enemy Act, the International EmergencyEconomic Powers Act and any regulations thereunder. Any transfer of technical data outside the United States by anymeans, including the Internet, is an export control requirement under U.S. law. In particular, but without limitation, none ofthe Program, its Documentation, or underlying information of technology may be downloaded or otherwise exported orreexported (i) into (or to a national or resident, wherever located, of) Cuba, Libya, North Korea, Iran, Iraq, Sudan, Syria, orany other country to which the U.S. prohibits exports of goods or technical data; or (ii) to anyone on the U.S. TreasuryDepartments Specially Designated Nationals List or the Table of Denial Orders issued by the Department of Commerce. Bydownloading or using the Program or its Documentation, you are agreeing to the foregoing and you are representing andwarranting that you are not located in, under the control of, or a national or resident of any such country or on any such listor table. In addition, if the Program or Documentation is identified as Domestic Only or Not-for-Export (for example, on thebox, media, in the installation process, during the download process, or in the Documentation), then except for export toCanada for use in Canada by Canadian citizens, the Program, Documentation, and any underlying information or technologymay not be exported outside the United States or to any foreign entity or foreign person as defined by U.S. Governmentregulations, including without limitation, anyone who is not a citizen, national, or lawful permanent resident of the UnitedStates. By using this Program and Documentation, you are agreeing to the foregoing and you are representing andwarranting that you are not a foreign person or under the control of a foreign person.SilkRoad RedCarpet WebService GuideDocument Version: August 2014Product Version: RedCarpet v 2014.3.0Technical SupportSilkRoad technology, inc.Web: http://support.silkroadtech.comPhone: 866-329-3363Headquarters20 West Kinzie Street, Suite 1220Chicago, IL 606541 (866) 329.3363 toll free (U.S. only)+1 (336) 201.5100 phone+1 (336) 201.5141 faxwww.silkroad.com

RedCarpetTable of ContentsRedCarpet Web ServiceOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Methods to Retrieve Employee Data . . . . . 1Methods to Import and Update Employee Data 1Methods to Launch Events, Retrieve Forms, and Retrieve Documents 2Upload Category Data . . . . . . . . . . . . . . . . 2Using RedCarpet Methods . . . . . . . . . . . . . . . . 3Background on the RedCarpet Methods . . 3Web Service URL . . . . . . . . . . . . . . . . . . . . 3Logging in to Consume the Service . . . . . . . 3Chapter 1: RedCarpet Retrive User Data APIRetrieve User Attributes . . . . . . . . . . . . . . . . . . 6Employee ID Types . . . . . . . . . . . . . . . . . . 6GetUserIDList . . . . . . . . . . . . . . . . . . . . . . 8GetUserProfileEx2 . . . . . . . . . . . . . . . . . . 15GetUserProfileEx . . . . . . . . . . . . . . . . . . . 21GetUserProfile . . . . . . . . . . . . . . . . . . . . . 25Chapter 2: User Import and Edit APIOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Import New Users . . . . . . . . . . . . . . . . . . . . . . 29BulkUserUpload . . . . . . . . . . . . . . . . . . . . 29Edit Existing Users . . . . . . . . . . . . . . . . . . . . . 33XMLUserEdit . . . . . . . . . . . . . . . . . . . . . . 33Chapter 3: Event and Task APIsEvents APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Input Specifications . . . . . . . . . . . . . . . . . 35Output Specifications . . . . . . . . . . . . . . . . 41Sample xmlEventData . . . . . . . . . . . . . . . 41LaunchEvent Method . . . . . . . . . . . . . . . 42UpdateEvent Method . . . . . . . . . . . . . . . . 48Task APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Input Specifications for Add and Delete Task Methods 54Input Specifications for GetTasks and Complete Task Methods 55Output Specifications . . . . . . . . . . . . . . . . 55AddTask Method . . . . . . . . . . . . . . . . . . . 56AddTaskEx Method . . . . . . . . . . . . . . . . . 59DeleteTask Method . . . . . . . . . . . . . . . . . 64GetTasks . . . . . . . . . . . . . . . . . . . . . . . . . 69CompleteTaskEx . . . . . . . . . . . . . . . . . . . 78Chapter 4: Forms and Documents APIForms and Documents APIs . . . . . . . . . . . . . . 85Retrieve Existing Forms . . . . . . . . . . . . . . . . . 85GetFormsIDs and GetCompletedForms . . 86User Import and Edit iii

RedCarpetGetFormsIDsEx and GetCompletedFormsIDsEx 98GetFormXML . . . . . . . . . . . . . . . . . . . . 105Mark a Form as Delivered . . . . . . . . . . . . . . 108Retrieve Populated PDF Files . . . . . . . . . . . . 112GetFormPDF . . . . . . . . . . . . . . . . . . . . . 113Delete Specified Form . . . . . . . . . . . . . . . . . . 114DeleteForm . . . . . . . . . . . . . . . . . . . . . . 114GetUploadedDocumentList . . . . . . . . . . . . . . 116GetUploadedDocument . . . . . . . . . . . . . . . . 122Chapter 5: Category UploadOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Category Upload . . . . . . . . . . . . . . . . . . . . . . 124CategoryUpload . . . . . . . . . . . . . . . . . . . 124Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 129GetEventReportEx . . . . . . . . . . . . . . . . . . . . 129GetEventReport . . . . . . . . . . . . . . . . . . . . . . 134Chapter 7: Using TransformationsOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Manage Transformations . . . . . . . . . . . . . . . 138Appendix ASample Code . . . . . . . . . . . . . . . . . . . . . . . . . 142User Import and Edit iv

RedCarpetRedCarpet WebServiceOverviewRedCarpet provides a web service for administrators to takeadvantage of RedCarpet features through an API. RedCarpetmethods exist in these general categories of features:1 An interface to retrieve RedCarpet user information2 An interface to perform a user import and edit3 An interface for LifeCycle events and forms.4 An interface for Category Uploads.Methods to Retrieve Employee DataFour methods are available to retrieve employee data. Onemethod returns a list of RedCarpet user ids and the other threeaccept a user id and return data about the specified user. TheRedCarpet method to return a list of user ids is available toretrieve all the users in the system or just the users that havemodified since the last retrieval.Three RedCarpet methods are available to retrieve RedCarpetemployee information based on user id. All three methodsprovide detailed output including employee profile data, extendeduser profile (custom) data, key property attributes, assignmentcategory attributes, team membership, and event information.One method outputs string arrays and the other two usermethods output an XML record.Methods to Import and Update EmployeeDataRedCarpet allows new users to be created and existing users tobe edited through a user import. An import method is provided tocreate new users (with or without a lifecycle event) and an editmethod is provided for existing users.The RedCarpet user import feature can be used for allemployees. New employees can be created as pending userswith very minimal information. Pending users are then reviewed, Employees can be imported tobenefit from an event and /or tocomplete tasks on behalf of anotheremployee.Web Service 1

RedCarpetand approved as active users through the RedCarpet user interface.Alternatively, if all required data is available at the time of the import, newemployees can be created, and established immediately as active users without areview.Existing active employee information can be edited via the API which (also) passesan XML record to update employee information.Methods to Launch Events, Retrieve Forms, and RetrieveDocumentsThe RedCarpet API includes methods to launch and update a LifeCycle event andretrieve RedCarpet forms.LifeCycle Event APILifeCycle event methods are available to launch a new lifecycle events or updateexisting events. As noted above, the user import API allows for an event to belaunched when an employee is created. The launch and update event methodsaccommodate event management on existing employees. Methods to add anddelete tasks from existing events are also available.Forms APIA RedCarpet implementation includes the Eprise web service allowingprogrammatic access to retrieve and delete saved forms outside of the RedCarpetapplication. The available web methods include options to:• retrieve completed forms based on various filter criteria• retrieve PDF files (populated through RedCarpet)• indicate whether a form has already been retrieved• delete existing formsUpload Category DataRedCarpet category upload methods allows RedCarpet administrators to importand update category values and modify the hierarchy of the category structure. Inaddition to facilitating the integration with other applications the “Import and ExportCategory Management” feature eases maintenance of category value changes.Prior to RedCarpet v 2.3 administrators could create and updated categories andcategory values through the Manage Categories menu option from the userinterface. Also through the interface an administrator could import category valuesusing XML syntax through the Import Category Values menu option.RedCarpet v 2.3 significantly expanded the features of the XML import syntax.Administrators can now update category values, and replace category values. Thereplace functions allow administrators to move child nodes and restructure thecategory value tree.The specifications of the XML syntax can be found in the Category Upload Guide(“RCCategoryImport.pdf”)User Import and Edit 2

RedCarpetUsing RedCarpet MethodsBackground on the RedCarpet MethodsRedCarpet uses an underlying content management engine called “Eprise” to:store the user data, handle the form templates and saved forms, and build andmanage the integrated RedCarpet portals. The Eprise content managementdatabase handles all of RedCarpet’s content maintenance and security. This istransparent to our users. As an administrator using the RedCarpet API, you willuse the Eprise web service to consume methods applicable to RedCarpet.Web Service URLThe web service is referenced with the following URL:https:///eprise/WebServicesA description of the available methods of the Eprise web service is:https:///eprise/WebServices?WSDL The APIreferences thenaming conventionof the underlyingcontentmanagementengine called“Eprise”. Note: All of yourRedCarpet pagesare served overSSL.While the majority of these methods do not apply to RedCarpet, you may use thispage for verification of applicable methods and their parameters.Logging in to Consume the ServiceWhile the WSDL is public, consuming the RedCarpet services requiresauthentication.The first parameter of each available method is a valid Eprise session id. A validEprise session id is obtained by logging in as a RedCarpet employee with thecorrect privileges. It is important to note all RedCarpet methods are constrained bythe same security (authentication and authorization) rules as the RedCarpet userinterface (performing the same function).Best practice is to log in, execute the applicable methods, then log out. Note: RedCarpetrole membership(and privilegeassignment) maybe set up by yourRedCarpetsystemsadministrator.Method name: LoginLogin to obtain a valid session id.• ParametersstrLogInIdValid Login ID of a privileged RedCarpetemployee.stringThe required employee privileges correlateto the privileges required for each methodexecuted.strPassword Corresponding password stringUser Import and Edit 3

RedCarpetstrRemoteIPOptional. In most cases this parameterdoes not apply to RedCarpet methods.stringPopulate this parameter only if thisuser is being authenticated by anexternal authentication server. Ifapplicable, the strRemoteIP expectsONE machine IP Address ofauthentication server (“remotebrowser”).• ReturnssessionID(simple string) — valid Eprise session id““(empty string) — unsuccessful login• Code examplePSWebService service = new PSWebService();service.Url = "https://example.silkroadtech.com/eprise/WebServices";String sessionnum = service.LogIn("Jim.Smith","$xxx123$","");if (sessionnum == ""){Console.WriteLine("Could not log in. Be sure password and URLare correct");return;}Method name: LogoutLog out to terminate the session.• ParametersstrSessionNumValid SessionNum returned by the LoginID method.stringShould be called for each coorespondingLogin call.User Import and Edit 4

RedCarpet• Returns1 — successful logout• Code exampleS = service.LogOut(sessionnum)User Import and Edit 5

RedCarpetChapter 1: RedCarpetRetrive User DataAPIRetrieve User AttributesThe following methods are available to retrieve employeeattributes:1 GetUserIDList accepts a synchronization token returning alist of userIDs and returns an XML document containing oneor more users meeting the synchronization criteria. The userIDs can be used as input to the GetUserProfile,GetUserProfileEx, GetUserProfileEx2 methods to retrievespecic user attributes. GetUserIDList allows you tosystematically retrieve all the users in the system andsubsequently retrieve all the users that have been modifiedsince the successfully processed user.Note: This guide uses the terms “user”and “employee” synonymously.2 GetUserProfileEx and GetUserProfileEx2 return all attributesassociated with any active RedCarpet user.GetUserProfileEx2 includes additional fields includingaddtional E-Verify case data, and two additional user ididentifiers. Both methods output an xml document withname\value pairs for all attributes.3 GetUserProfile returns an array of attributes associated withany active RedCarpet user. GetUserProfile returns a subsetof the attributes returned by GetUserProfileEx.The result of GetUserProfile provides a table with two arraysof data. The first array is a list of standard and extended userattribute names. The second array contains thecorresponding values. unique form ids.Employee ID TypesUsers are uniquely identified in RedCarpet based on yourimplementation.You may query user data based on the appropriate RedCarpetuser for your implementation. All of these options are returned byGetUserIdList. The following criteria are available to be used toidentify a user:Web Service 6

RedCarpet• LoginID - required for all users. LoginID is required to be unique inRedCarpet.• Email - require for all users. Email is required to be unique based on aconfiguration setting.• Guid - a (RedCarpet) generated system key. Guid is unique forRedCarpet users. It is not exposed through the RedCarpet userinterface.• LifeSuiteID - a (SilkRoad Technology) generated system key. This isunique for all LifeSuite users. It is not exposed through the RedCarpetuser interface. This key exists for integrating user data across theLifeSuite applications. The LifeSuiteID can be used as an inputparameter with GetUserProfileEx2, BulkUserUpload, XMLUserEdit, andGetUploadedDocumentList.• Employee_HRISID - optionally configured for collection through theRedCarpet interface. Employee_HRISID is optionally configured to berequired. It is unique for RedCarpet users. This field exists to crossreference an employee with their ID in another (external corporate)system. It’s label and value is configured and populated based oncustomer specific requirements. SilkRoad recommends you populatethis value for system cross reference.The Employee_HRISID can beused as an input parameter with GetUserProfileEx2, BulkUserUpload,XMLUserEdit, and GetUploadedDocumentList.• SSOAuthParam - optionally configured and referred to as “externalauthentication”. The authentication parameter is the user id used toauthenticate in an externalsystem. RedCarpet uses this parameter whenit is configured for “single sign on”. Customers may choose to populatethe SSOAuthParam with the external system identifier even if they arenot using external authentication. The SSOAuthParam can be used asan input parameter with GetUserProfileEx2, BulkUserUpload,XMLUserEdit, and GetUploadedDocumentList. For backwardcompatibility BulkUserUpload and XMLUserEdit also accept“AuthParam”User Import and Edit 7

RedCarpetGetUserIDListUsageGetUserIDList returns a list of user id’s that match the search criteria. The list canbe all the users in the system or all the users who have been updated since thespecified synchronization token marker.The synchronization token marker is a system value and not a user generatedvalue. For subsequent calls you will populate the from theresult of GetUserIDList to return the user updates since the successfullyprocessed user record.The users are returned sorted by last modified date time. The last user in the list isthe most recent modified user in the system.To return all the users in RedCarpet call GetUserIDList passing a null for thesynchronization token. RedCarpet will return a user ids listing every user in thesystem ordered by last modified.To retrieve a set of users that have been updated since a point in time, you mustcall GetUserIDList using the last sychronization token return in the previousresults set.By default, your GetUserIDList results set will be limited to 1000 employees percall. The maximum results set is defaulted to 1000 employees. If you want tochange the maximum results set size, contact SilkRoad technical support todiscuss why you want to change the configuration value of "GetUserIdList MaxRecords Returned". For performance reasons, SilkRoad does not recommendmodifying the results set size to more than 1000 rows, but it is configurable if yourintegration justifies a different (smaller) paging value.The intent of the maximum is for the calling app to page through the results set.For example, assume the maximum records configuration (MaxRecords) is set to1000. If you are calling GeUserIDList and your results set is < MaxRecords thenyou have returned all the records updated since the last synchronization token.If the number of rows returned equals the MaxRecords, call the method again(passing in the last synchronization token value) and return the next 1000 records.Continue calling GetUserIDList until the results set is less than MaxRecords. Anumber less than the MaxRecords indicates the last page of data (no employeerecords have been updated since the last synchronization token).When using this technique to synchronize data from RedCarpet to an externalsystem, it is important for your external system to allow duplicates.Any updates to the following user attributes will be recognized as a user update:• Employee details• Employee User Profile• Key Properties• Event status change (an event is launched, event completed, or eventcancelled )User Import and Edit 8

RedCarpet• E-Verify Case data (Resolve Code, Resolve Date, Create Date, ReferralDate,Close Date, Last Message,Manual Case Number,Manual CaseSubmitted By, Manual Resolve Date)Assignment categories, team membership, modifying event values, task updates,and document uploads do not trigger a change to the user data.For example after calling GetUserIDList with a synchronization token, the returnlist of ID’s could be passed to GetUserProfileEx2 to obtain the employeeinformation for each employee who has been updated since the last call.If search criteria is specified that does not match any data, no data is returned.Input for GetUserIDListstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below. The XMLspecifies your sychronization starting point.You may return all the Users in the system(with their tokens) or return all the usersmodified since the token specified.Examples of GetUserIDList strXMLExample of GetUserIDList strXML to return a list of all users and their currentsynchronization token in RedCarpet::Example of GetUserIDList strXML to return a list of users updated since thespecified token:yx+c9VyG1HwjHsIo0j8z0jd47aKGEJicwWywoYsnn7hm3wo+3KfH87DN3GNxFKWP0baBmbdcltuVKKwoFzDA7Q==User Import and Edit 9

RedCarpetNodes in GetUserIDListNode Description NotesXML Document headerParent nodeSynchronization tokenmarker for where to beginthe results set.Null returns all user recordsin update order. The mostrecent update will be the lastin the results set.Requiredindicates a null value.The synchronization token is a simplestring and should be stored as a string.A valid synchronizationtoken (obtained by aprevious call to this method)returns all users updatedsince the last call.close parent nodeUser Import and Edit 10

RedCarpetReturnsAn XML document defined as:No Error1Return code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code description return code descriptionThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedAn xml document containing the user ids of the employees that meet thesynchronization criteria. The nodes in the return data are as follows:User Import and Edit 11

RedCarpetActiveXML document headerOccurs once for each documentoccurs once for each documentoccurs once for each user returnedGuid is a unique RedCarpet system valuereturned for each userEmployee_HRISID returned if populatedthrough RC. Optionally configured asrequired.SSOAuthParam returned if populatedthrough RC. Configured ifauthentication type is externalconfiguration. Optionally configured ifstandard authentication.LoginID is required and unique inRedCarpetEmail is required and optionallyunique.LifeSuiteID is a unique LifeSuitesystem populated value returned if ithas been assigned by a LifeSuiteapplicationEmployeeStatus returns Active orRetired for each user.SynchronizationToken>Synchronization Token is a systemgenerated value returned for each user.The token’s sole purpose is tosynchronize updates between RedCarpetand an external system.End User node. Occurs once for eachuserEnd Users list. Occurs once for eachdocumentUser Import and Edit 12

RedCarpetGetUserIDList Error Messages ValueValueValueDescriptionError Invalid input XML: {0} 42000ErrorErrorThe synchronization tokenwas provided cannot beused for this web servicemethod. It may have beenreturned from a differentweb service and cannot beused with this web service,with the criteria specified.The synchronization tokencannot be decrypted andappears to have beentampered with42001 Invalid Synchronization token42002 Invalid Synchronization tokenCode exampleTo return a list of all the users in RedCarpet:d= service.GetUserIDList(sessionnum,"")User Import and Edit 13

RedCarpetSample OutputThis sample output includes only two users for readability.No Error156e6f1f7-aab1-43ca-9c5900c2b95d70871001Tammy.Jonestjones@MySRT.comActiveyx+c9VyG1HwjHsIo0j8z0jd47aKGEJicwWywoYsnn7hm3wo+3KfH87DN3GNxFKWPDurca47G1jt1uqNOUx470Q==0ce54d80-c93d-4844-842534a6863009c3James.Jonesjjone@MySRT.comActiveyx+c9VyG1HwjHsIo0j8z0jd47aKGEJicwWywoYsnn7hm3wo+3KfH87DN3GNxFKWPgTwFRsYrvF3u/PCOyIVOjQ==]]>User Import and Edit 14

RedCarpetNode Description NotesID typeRequired.Accetable values are:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIDSee “Employee ID Types” on page 6 fordescription.example:LoginID ID value Required.Specific to unique identifier for eachuser. This value is coupled to theEmployee ID Type specified.Example: Tammy.Jones close node Requiredclose parent nodeRequiredUser Import and Edit 16

RedCarpetReturnsAn XML document defined as:No Error1ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code description return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataAn xml document with user data. User data includes: employee detail,employee profile fields, key properties, assignment categories, launched event(including event status) and the event data including event named people,categories and dates, and e-verify case data if applicable.Extended attributes are included in the string after the standard attributes.GetUserProfileEx2 Error Messages ValueUserErrorUserErrorValueThe LoginId ({0}) used toidentify a user is used bymore than one userNo user could be found forthe id: {0}Value3105931060User Import and Edit 17

RedCarpetSample OutputNo Error1TammyJones56e6f1f7-aab1-43ca-9c5900c2b95d7087Tammy.JonesStandard10012012-12-040East KingstonUser Import and Edit 18

RedCarpetAbstractCategory_5LocationBostonLOC_BOS\All Locations\BostonReporterOnboarding-EVerify7CompleteEvent_7Person_1ManagerRobert ManagerRobert.ManagerRobert.Manager@MySRT.com101UserGUID>0251e061-1e67-42e2-b41469db2e6eb60a

RedCarpet96607afd-293f-42be-b85dfa66eeb109b9EELIG2012-12-042012-12-042012-12-04The employee continues to work forthe employer after receiving an Employment Authorized result. ]]>User Import and Edit 20

RedCarpetGetUserProfileExUsageRetrieves standard and extended user attribute information for a specified user.Parameters for GetUserProfileExstrSecurityTokenRequired.simple stringstrLoginIDValid Session ID for consuming serviceRequired if strFKUserID is not populated.simple stringRedCarpet login id on the employeeprofile. This is a unique identifier for theemployee.strFKUserIDThis parameter is mutually exclusive ofstrFKUserID. Specify an empty string if youare specifying a value for strFKUserID.Required if strLoginID is not populated.simple stringAlternate id for an employee from anothercorporate application. This is a uniqueidentifier for the employee.This parameter is mutually exclusive ofstrLogInID. Specify an empty string if youare specifying a value for strLogInID.strAlternateUserID reserved for future use simple stringReturnsA table of type EpsTableEx.The structure is:EpsTableEx{String ErrorString;int ErrorNum;String[][] Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.User Import and Edit 21

RedCarpet““ or “xxxx” — return code description return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataAn xml formatted string.Extended attributes are included in the string after the standard attributes.Code exampleTo return user attributes for a standard RedCarpet user with the externalauthentication parameter of “JJohnson”:Eprise.EpsTableEx t = service.GetUserProfileEx(sessionnum,"", "JJohnson","")Sample OutputThis sample output has the redundant nodes compressed for readability. Thissample includes all the standard attributes and multiple extended attributes. Theextended attributes examples include: phone number, a drop down list selection ofInterests, and a comma separated multi-select called “Days_avail”.This is an example of an employee benefiting from an event. This employee is notdefined as a provider as evident by no assignment categories or teammembership. Example category output is displayed in the event categories.User Import and Edit 22

RedCarpet- - JaneLLeeJohnson7c60d370-6679-40c1-a57411ddf41dcdb0Jane.JohnsonStandareJJohnsonjane.johnson@work.comBooks1,3,5,7- Onboarding1InProgresshwisehwise@work.com- ManagerTrish Madisontrish.madisontrish.madison@work.comUser Import and Edit 23

RedCarpet+ HR CoordinatorHarry Wisehwisehwise@work.com- LocationBedford\All Locations\United States\Massachusetts\Bedford+ DepartmentEngineering\All Departments\Engineering+ Job TypeEngineer\All Job Types\Engineer- Start2008-07-25User Import and Edit 24

RedCarpetGetUserProfileUsageRetrieves standard and extended user attribute information for a specified user.Method output is an array of strings.Parameters for GetUserProfilestrSecurityTokenRequired.simple stringstrLoginIDValid Session ID for consuming serviceRequired if strFKUserID is not populated.simple stringRedCarpet login id on the employeeprofile. This is a unique identifier for theemployee.strFKUserIDThis parameter is mutually exclusive ofstrFKUserID. Specify an empty string if youare specifying a value for strFKUserID.Required if strLoginID is not populated.simple stringAlternate id for an employee from anothercorporate application. This is a uniqueidentifier for the employee.This parameter is mutually exclusive ofstrLogInID. Specify an empty string if youare specifying a value for strLogInID.strAlternateUserID reserved for future use simple stringReturnsA table of type EpsTableEx.The structure is:EpsTableEx{String ErrorString;int ErrorNum;String[][] Data;}ErrorStringUser Import and Edit 25

RedCarpetReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code description return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataTwo string arrays. The first contains the attribute names. The second containsthe corresponding values to the name.Extended attributes are included in the array after the standard attributes.Code exampleTo return user attributes for a standard RedCarpet user with the login id of“john.james”:Eprise.EpsTableEx t = service.GetUserProfile(sessionnum,"john.james","")User Import and Edit 26

RedCarpetSample OutputThis sample output includes all the standard attributes and one extended attributecalled “EmergencyContactInfo”.OBJECTIDUSERGUIDLOGINIDFKUSERIDDEPARTMENTLOCATIONPOSITIONMANAGER_EMAILONBOARDING_MANAGER_EMAILUser_TypeUser_IDHire_DateFirst_NameMiddle_InitialLast_NameEmailPendingLoginIdEmergencyContactInfoUser Import and Edit 27

RedCarpet4478e4cc00a5-79a4-4c47-8019e8fd005963f3john.jamesjjamesCustomer ServiceEastManagerOnboarding Managere4cc00a5-79a4-4c47-8019e8fd005963f32007-03-06rcexampleUser Import and Edit 28

RedCarpetChapter 2: UserImport and Edit APIOverviewThe user import API allows a bulk update and bulk edit ofemployees in the system using an XML document as the inputparameter.The XML syntax for defining employees is documented in aseparate document called the User Import Guide (named“RCBulkUserImportandEdit.pdf”). The User Import Guidedescribes the syntax and all of the return codes for the bulkimport and edit features as well as the processing of pendingusers through the RedCarpet interface.Import New UsersAn XML record used to create both pending and active users.BulkUserUploadUsageUsed to create one our more new users using an XML formattedfile.ParametersstrSecurityTokenRequired.simple stringxmlUserDataValid Session ID for consuming serviceRequired.simple stringXML record formatted as described inChapter 1 of the User Import Guide.ReturnsA table of type EpsStringEx.Web Service 29

RedCarpetThe structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataString containing XML record with error descriptionUser Import and Edit 30

RedCarpetCode examplesTo import new RedCarpet users from an XML record.string sUsers = “+“” +“Jane”+“Brown”+“Jane.Brown”+“Jane.Brown05@silkroadtech.com”+“1”+“$JaneBrown$”+“John”+“Smith”+“John.Smith”+“John.Smith@silkroadtech.com”+“1”+“$JohnSmith$”+“”Eprise.EpsStringEx ret = service.BulkUserUpload(sessionnum,sUsers);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying import users" + " Error:" +ret.ErrorString);return;}Example return ret.Data String:2 active users created0 pending users createdParsing started at Thursday, July 24, 2008 1:43:38 PM and ended atThursday, July 24, 2008 1:43:38 PMTotal duration: .0598 seconds (.0465 seconds were spent creatingusers)User Import and Edit 31

RedCarpetJane BrownJohn SmithUpload finishedBulk Import Error CodesError codes are returned in the same format for the post and the method call. Seethe User Import Guide for error code information returned in the Data string.User Import and Edit 32

RedCarpetEdit Existing UsersAn XML record used to update active users.XMLUserEditUsageUsed to update one our more existing active users using an XML formatted file.ParametersstrSecurityTokenRequired.simple stringxmlUserDataValid Session ID for consuming serviceRequired.simple stringXML record formatted as described inChapter 2 of the File Import GuideReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataString containing XML record with error descriptionUser Import and Edit 33

RedCarpetCode examplesTo update an two active RedCarpet users from an XML record.string sUsers = “”+“”+“Jane.Brown05”+“Boston”+“John.Smith”+“Boston”+“”Eprise.EpsStringEx ret = service.XMLUserEdit(sessionnum,sUsers);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying import users" + " Error:" +ret.ErrorString);return;}Example return ret.Data:2 users modifiedUpload finishedXMLUserEdit Error CodesError codes are returned in the same format for the post and the method call. Seethe “User Import Guide” for error code information returned in the data string.User Import and Edit 34

RedCarpetChapter 3: Event andTask APIsEvent and task related APIs are available to create and editemployee events programmatically. The task APIs allow tasks tobe added and deleted from existing events.In all cases of executing the event and task methods, the eventand task definition must be predefined (through the administrativepages of the Red Carpet interface).Events APIsTwo methods are available to manage employee events• launch a new event for an existing employee• edit an existing LifeCycle eventThe Event definition must be defined through the RedCarpet userinterface. Fields defined in the event definition determine theattributes of the event record passed to the Events methods.Input SpecificationsBoth of the event methods (launch a new event and update anexisting event) use two arguments.1 A Session Id as described in “Logging in to Consume theService” on page 3 of this document.• The RedCarpet user executing the Events methods mustbe a member of the Event Coordinator team for eachevent included in the Events record.Note: SessionID for event methodsmust include Event Coordinatormembership.2 An XML document containing one or more events. EachEvent in the XML identifies the employee benefiting from theevent, and the field values of the event.• The event record, called “xmlEventData”, uses the samesyntax for each method. The syntax is described below.Web Service 35

RedCarpet• The requirements of the LaunchEvent method differ from the UpdateEventmethod. The rules are outlined with each event.Field Descriptions of the xmlEventDataThe second parameter of each Event method is an XML document passed as asimple string. The string contains an Events record with the following generalformat:Note: See below foradditionalinformation on tagsfor events.• The root element is .• The parent element, occurs once for each event to be launched.The record is composed of two parts:1The child element must contain one of the unique user identifiers describedbelow.2Child and subchild elements to populate or update the event fields as definedon the event definitions. The syntax to match the event definition isdescribed below.Details of the Input recordTwo parts of the input record are:Part One: an element to uniquely identify an employee to benefit from the event orthe event update.You may one of choose from three techniques to uniquely identify an employee forLaunchEvent and UpdateEvent. Three techniques are available for backwardcompatibility.1 Four elements are provided to choose from. The naming convention ofelements used for unique identifiers are prefixed with “ForWhom_”. The recordshould contain only one of these options. If you are using an externalapplication to authenticate your users, SilkRoad recommends you useForWhom_AuthParam to identify each user.Note: SilkRoadrecommends usingtheForWhom_AuthParam“ForWhom” IdentifierForWhom_LoginIdForWhom_AuthParamForWhom_EmailForWhom_GuidDescriptionRedCarpet LoginId for employees using StandardAuthenticationLoginID for employees using External Authenticationemployee Email address if the employee email address isunique.RedCarpet creates and stores a GUID for each employee.This value is returned from GetUserProfileEx method.User Import and Edit 36

RedCarpet2 You may use this flexible technique allowing your to set the identifier type byspecifying it as a value. Note: f you want to identify the user by the LifeSuiteIDor the EmployeeHRISID your must use either this technique or the next.where EmployeeIDType is on of the values described in See “Employee IDTypes” on page 6.3 LaunchEvent and UpdateEvent also accept this syntax.where EmployeeIDType is on of the values described in See “Employee IDTypes” on page 6.Part Two: The named event to be launched or updated it’s corresponding eventfield(s)The naming convention of the subchild element tags is determined by thefields defined in the event definition (in the RedCarpet user interface).• Each defined non-category field uses a Name / Value pair syntax• Each defined category field uses a Name / Value / Type syntax.When creating your event syntax a LifeCycle event note that Event categories arepopulated with a single value for each category.The event categories are child nodes of the element. Other than theparent element, the same syntax is used for the Event as used in the user importsyntax.User Import and Edit 37

RedCarpetA description of event field names is as follows:RequiredElement SyntaxStatus if anevent isincludedDescriptionCategory Yes Occurs for each category defined on the eventExample syntax:Name Yes Occurs once as a child element of for eachcategory element defined on the eventValid values are text as it is entered in the “Alias Name” field ofthe Manage Events page.Example syntax:LocationValue Yes Occurs once as a child element of for eachcategory element defined on the eventValid values are based on the element.If Name is specified, valid values are text as it isentered in the “Category Value” field of the Manage Categoriespage.Example syntax:North EastCode is the recommended Name/Value/Type set touse.Name can not be used if duplicate values existwithin your category tree. See User Import and Edit 38

RedCarpetElement SyntaxRequiredStatus if anevent isincludedDescriptionType Yes Occurs once as a child element of for eachcategory element defined on the eventValid values are:• Code - value is the category codeMA_BEDFORDCode• Name - value is the field nameBedfordName• Path - value contains pathAll Locations\UnitedStates\Massachusetts\BedfordPath specifies the type of value is passed in the value field toassociate the correct category with the event or user.Code is the recommended Name/Value/Type.SilkRoad recommends the use of the Code type to promote amaintainable process in case category values are renamed ormoved.Name can not be used if duplicate values existwithin your category tree.IThe syntax rules for Event Categories are:1 Each Category is coupled with three child elements:abc2 Category Values, each value is listed for the corresponding “Value” node inthe XML syntax.User Import and Edit 39

RedCarpetNon-category field syntax:Element SyntaxRequiredStatus if anevent isincludedDescriptionPerson Yes is a parent element.Occurs one time for each named person.on the event.Name Yes Child element of Valid values are text as it is entered in the “Person Name” field ofthe Manage Events page.Example:HR CoordinatorValue Yes Child element of Valid value is a specific person who is a member of the specified(Person Name) Team on the Manage Events page. The specificperson can be identified by one of these unique identifiers:• email address*• user GUID• login ID• External Authentication ID*If email address is not unique it is not a valid identifierExample:George.RogersDate Yes is a parent element.Occurs one time for each “date name” defined on theevent.Name Yes Child element of Valid values are text as it is entered in the “Date Name” field of theManage Events page.Example:StartValue Yes Child element of Date value to corresponding Expected format is YYYY-MM-DDUser Import and Edit 40

RedCarpetOutput SpecificationsSimilar to the BulkImport and XMLEditUser methods, each method returns a tableof type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorString and Error NumThe value of ErrorNum should be checked for a the value not equal to 1 todetermine an error description vs. a success message.If the ErrorNum returns a 1 the ErrorString is equal to “No Errors”.If the ErrorNum returns a value not equal to 1 the ErrorString is equal to “Therewere errors”. Errors are described in the Data string.DataAn XML record describing either the successful event modifications or a detailof the reason for failure.If one record or more is in error, the ErrorNum returns a value notequal to 1. The XML in the Data string will describe the errors. The errors areoutlined with each event.Sample xmlEventDataA sample of Events record used in the Events methods is as followsUser Import and Edit 41

RedCarpetLaunchEvent MethodLoginIDJames.DevelinOnboarding-EVerifyOnboarding CoordinatorAmy.HrCoord@mySRT.comManagerRobert.Manager@MySRT.comStart2012-12-12DepartmentCustomer ServiceNameLocationBostonNameUsageUsed to programmatically launch an event for an existing employee.User Import and Edit 42

RedCarpetCode examplesTo launch a LifeCycle event an XML record.string sEvents = ‘’ +" " +" " +“ LoginID" +“ James.Develin" +“ " +" Onboarding " +" " +" HR Coordinator " +" hwise@redcarpet.com " +" " +" " +" Manager" +" mbloom@redcarpet.com" +" " +" " +" Start" +" 2008-11-13" +" " +" " +" Department" +" MRKNG" +" Code" +" " +" " +" Job Type " +" 810SALES" +" Code" +" " +" " +" Location" +" NE_FRA" +" Code" +" " +" " +""”Eprise.EpsStringEx ret = service.LaunchEvent(sessionnum,sEvents);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while launching events" + " Error:" + ret.Data);return;}User Import and Edit 43

RedCarpetParametersstrSecurityTokenRequired.simple stringxmlEventDataValid Session ID for consuming serviceRequired.simple stringXML record formatted following the rulesoutlined in “Field Descriptions of thexmlEventData” on page 36.The LaunchEvent method has the same requirements as launching an eventthrough the RedCarpet interface. The requirements are as follows:1 All fields defined in the event definition are required in the record.2 An employee is limited to a single active event of an event type.3 An employee must be active to have an event launched on their behalf.4 Tasks and notifications are generated for the employee at the time the event issuccessfully created.Method ReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.Error codes are returned in the same format for the post and the method call.ErrorNumThis variable indicates success or failure. Values are:Data1 (one) — method succeeded0 (zero) — method failedUser Import and Edit 44

RedCarpetA record will be returned with descriptive XMLThe elements of the record returned in the data string followsSample output for the data string for 2.8.0 and higher:Element Syntax Value DescriptionLaunchEventResultsParent node.Note X event created Successful event count. Present for Successand Failure.X event not createdParsing started at...Total duration:.x seconds (seconds were spentcreating events)Unsuccessful event count. Present for Successand Failure.Date and Time of method execution. Presentfor Success and Failure.Time to execute method. Present for Successand Failure.EventError Parent node Exists only for an Event that failsForWhom_* unique identifier value of benefiting employee ForWhom_ identifier to identify employeewhose event failedName Event name Event name identifying event in errorError Parent node The following Error format is returned foreach error that occurs:See next tableSee next table See next tableSample output for LaunchEvent:1 events launchedfb08d035-a436-4f05-85237a07073a28483008Nate.EbnerEbner@mysrt.comUser Import and Edit 45

RedCarpetOnboarding-EVerify440 events not launchedParsing started at Friday, December 14, 2012 12:11:40 PM andended at Friday, December 14, 2012 12:11:41 PM Note: by default the LaunchEvent output is transformed to 2.7.x output. In order toreturn output in this format you must disassociate the LaunchEvent operationXLST. See see “Default Configuration” on page 138 for additional information.LaunchEvent Error Codes ValueValueValueDescriptionEvent ExistsInvalid InputInvalid InputNamed event alreadyexists for user: ForWhomFailed to parse XMLdocumentsFailed to add event to useras the sessionid executingthe method is not an eventcoordinator30000 Duplicate Event30001 Caused by malformed XML30002 Privilege errorInvalid Input Unknown event name 30003 Undefined Event nameInvalid InputInvalid InputInvalid InputInvalid InputInvalid category valuename for namedcategory:valueInvalid category value codefor named category:valueInvalid category value pathfor named category:valueNamed category does notexist on the Eventdefinition30004 The value in passed for Name did not match a valid categoryname30005 The value in passed for Code did not match a valid categoryCode30006 The value in passed for Path did not match a valid categoryPath30007 Launch data must map to field definedon the event definition.User Import and Edit 46

RedCarpet ValueValueValueDescriptionInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputNamed person does notexist on the EventdefinitionTheForWhom_AuthParamused to identify a user isnot used by any knownuserThe ForWhom_LoginIDused to identify a user isnot used by any knownuserThe ForWhom_Guid usedto identify a user is notused by any known userThe ForWhom_Email usedto identify a user is notused by any known userThe e-mail address used toidentify a user is used bymore than one userNo user identificationnode could be found forthe nth event nodeMissing person (manager)name or Missing person(manager) valueMissing EmployeeID Typefor named person on theevent30008 Launch data must map to field definedon the event definition.30009 Invalid value external authorizationparameter30010 Invalid value employee LoginID30011 Invalid value User GUID30012 Invalid value email address30013 Email address must be unique if it is to beused as the primary identifier30025 No valid ForWhom_* identifier wasprovided in the (specified) record30026 Person node included in record with no or node30056 Missing EmployeeIDType for a namedperson.Invalid Input Incorrect EmployeeIDType 31053 The EmployeeIDType {0} is unknown.Please use one of the following:LifeSuiteID, Employee_HRISID, Email,LoginID, GUID, or SSOAuthParam.Invalid InputMissing requiredinformation: message text34000 A required event field specified in themessage text has been omitted from therecord.User Import and Edit 47

RedCarpet ValueValueValueDescriptionInvalid Input Invalid Category reference 36015 {0} cannot be used because it is not a leafcategory value (i.e. It has child categoryvalues)UpdateEvent MethodUsageUsed to programmatically update one or more attributes of an existing event for anactive employee.Code examplesTo launch a LifeCycle event an XML record.string sEvents = ‘’ +" " +" nwhite213" +" Onboarding " +" " +" HR Coordinator " +" lsmith@redcarpet.com " +" " +“ " +""”Eprise.EpsStringEx ret = service.UpdateEvent(sessionnum,sEvents);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while updating events" + " Error:" +t.ErrorString);return;}User Import and Edit 48

RedCarpetParametersstrSecurityTokenRequired.simple stringxmlEventDataValid Session ID for consuming serviceRequired.simple stringXML record formatted following the rulesoutlined in “Field Descriptions of thexmlEventData” on page 36The UpdateEvent method has the same requirements as updating an eventthrough the RedCarpet interface. The requirements are as follows:1 Only the fields to be updated need to be included in the record.2 An employee must be active to have an event updated on their behalf.3 No new tasks are generated for the employee at the time the event issuccessfully updated.• The task status will be adjusted based on any date modifications• The Task Summary page will correctly reflect the updated values of theEvent in the Event Details section.4Any correctly privileged user (Event Coordinators) can manually add task toexisting events through the RedCarpet user interface, by using the “Add a Task”button on the Employee Task List page.Method ReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.Error codes are returned in the same format for the post and the method call.User Import and Edit 49

RedCarpetErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataAn XML record will be returned.An example return string is as follows:A sample return is a follows:No Error11 events updated78477262-a948-4ce4-bfc88a5b20f5ed7b3007James.DevelinDevelin@mysrt.comOnboarding-EVerify420 events not updatedParsing started at Monday, December 17,2012 4:10:15 PM and ended at Monday, December 17, 2012 4:10:17 PM]]>Note: by default the UpdateEvent output is transformed to 2.7.x output. In order toreturn output in this format you must disassociate the LaunchEvent operationXLST. See see “Default Configuration” on page 138 for additional information.UpdateEvent Error CodesThe elements of the record returned in the data string follows:User Import and Edit 50

RedCarpetElement Syntax Value DescriptionUpdateEventResultsParent node.Note X event created Successful eent count. Present for Success andFailure.X event not createdParsing started at...Total duration:.x seconds (seconds were spentcreating events)Unsuccessful event count. Present for Successand Failure.Date and Time of method execution. Presentfor Success and Failure.Time to execute method. Present for Successand Failure.EventError Parent node Exists only for an Event that failsForWhom_* unique identifier value of benefiting employee ForWhom_ identifier to identify employeewhose event failedName Event name Event name identifying event in errorError Parent node The following Error format is returned foreach error that occurs:See next tableSee next table See next table ValueValueValueDescriptionInvalid InputInvalid InputFailed to parse XMLdocumentsFailed to update event touser as the sessionidexecuting the method isnot an event coordinator30001 Caused by malformed XML30020 Privilege errorInvalid Input Unknown event name 30003 Undefined Event nameUser Import and Edit 51

RedCarpet ValueValueValueDescriptionInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid category valuename for namedcategory:valueInvalid category value codefor named category:valueInvalid category value pathfor named category:valueNamed category does notexist on the EventdefinitionNamed person does notexist on the EventdefinitionTheForWhom_AuthParamused to identify a user isnot used by any knownuserThe ForWhom_LoginIDused to identify a user isnot used by any knownuserThe ForWhom_Guid usedto identify a user is notused by any known userThe ForWhom_Email usedto identify a user is notused by any known userThe e-mail address used toidentify a user is used bymore than one userNo user identificationnode could be found forthe nth event node30004 The value in passed for Name did not match a valid categoryname30005 The value in passed for Code did not match a valid categoryCode30006 The value in passed for Path did not match a valid categoryPath30007 Update data must map to field defined onthe event definition.30008 Update data must map to field defined onthe event definition.30009 Invalid value external auth parameters30010 Invalid value employee LoginID30011 Invalid value User GUID30012 Invalid value email address30013 Email address must be unique if it is to beused as the primary identifier30025 No valid ForWhom_* identifier wasprovided in the (specified) recordUser Import and Edit 52

RedCarpet ValueValueValueDescriptionInvalid InputInvalid InputInvalid InputInvalid InputMissing person (manager)name or Missing person(manager) valueOnly categories can bemodified on completedevents.Missing EmployeeID Typefor named person on theeventForWhom_x identifiernode cannot be blank30026 Person node included in record with no or node30030 Event updates with a status of Completeare limited to category values.30056 Missing EmployeeIDType for a namedperson.31044 The ForWhom_x identifier specified inthe message text is blank in the record.Invalid Input Incorrect EmployeeIDType 31053 The EmployeeIDType {0} is unknown.Please use one of the following:LifeSuiteID, Employee_HRISID, Email,LoginID, GUID, or SSOAuthParam.Invalid InputMissing requiredinformation: message text34000 A required event field specified in themessage text has been omitted from therecord.Invalid Input Invalid Category reference 36015 {0} cannot be used because it is not a leafcategory value (i.e. It has child categoryvalues)User Import and Edit 53

RedCarpetTask APIsFour methods are available to interface with tasks from existing employee events:• Add a new task for an existing LifeCycle event for an employee• Delete an existing task from an existing LifeCycle event• Get the existing tasks for an existing LifeCycle event for an employee• Complete an existing active taskThe “Task Definition ID” field defined in the task definition is used as the uniqueidentifier of the task. The Task Definition ID is optional in the task definition butmust exist to add, delete, or complete a task through the API.Input Specifications for Add and Delete Task MethodsAdd a new task (AddTask) and Delete an existing task (DeleteTask) use similararguments:1 strSecurityToken - A Session Id as described in “Logging in to Consume theService” on page 3 of this document.• The RedCarpet user executing the methods must be a member of theEvent Coordinator team for each event included in the strEventNameparameter OR• The RedCarpet user executing the methods must be a member of a teamwith ViewAllTasks permissionNote: SessionIDuser privileges forevent methodsmust include EventCoordinatormembership.2 strForWhomUser - Any of the following employee profile attributes aresupported: the employee Login id, a unique email address, or the profileauthparam. The strForWhomUser parameter will also accept the programgenerated userguid.3 strEventName - The event name (in the default language) or event code as itis displayed on the Administration -> Localization page.4 strTaskDefinitionStringID - A unique identifier for the task as defined in the“Task Definition ID” field on the Edit Task Definition page (Administration ->Manage Events - Manage Events \ Manage Task Definitions \ Edit TaskDefinition page)After the Task Definition ID is entered and saved, it is visible on the ManageTasks list. In the example below, the Task Definition ID is “Transfer_Task1”5 strSendEmails - True to send notification the task has been added, false toskip sending notifications.6 strdontDeleteIfFormExists - Applies only to the DeleteTasks method. If a formis associated with the specified task (strTaskDefinitionStringID), a value ofUser Import and Edit 54

RedCarpetTrue will prevent the task from being deleted. A value of False will allow a taskwith an associated form to be deleted.Input Specifications for GetTasks and Complete TaskMethodsGetTasks and CompleteTaskEx methods use similar arguments:1 strSecurityToken - A Session Id as described in “Logging in to Consume theService” on page 3 of this document.• The RedCarpet user executing the methods must be a member of theEvent Coordinator team for each event included in the strEventNameparameter2 strXML - GetTasks and CompleteTaskEx accept an XML document to specifythe input filters for the method. The xml for each method is described below.Output SpecificationsEach method returns an XML document of the following structure: ErrorString and Error NumThe value of ErrorNum should be checked for a the value not equal to 1 todetermine an error description vs. a success message.ErrorNum indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedIf the ErrorNum returns a 1 the ErrorString is equal to “No Errors”.If the ErrorNum returns a value not equal to 1 the ErrorString is equal to “Therewere errors” or an error message. Errors are described in the Data string.DataAn XML record describing either the successful task data or a detail of thereason for failure.The Data record xml is returned as CDATA tag.User Import and Edit 55

RedCarpetIf one or more parameters are in error, the ErrorNum returns a value not equalto 1. The XML in the Data string will describe the errors. The error text in thedata string and error codes are described in the “Method Returns” section ofeach method description.AddTask MethodUsageUsed to programmatically add a task on an existing event for an existingemployee.Code examplesTo add a task with a Task Definition ID of “Transfer_Task1” to an event called“Transfer” for the employee with the loginID of “Jackson.Smith” the examplesyntax is as follows:.strForWhomUser = “Jackson Smith”eprise.epsstringex ret = service.AddTask(sessionnum,strForWhomUser, “Transfer”,“Transfer_Task1”, “true”);if (ret.errornum != 1){console.out.writeline("error while adding task" + " error:" + ret.data);return;}ParametersstrSecurityTokenstrForWhomUserRequired.Valid Session ID for consuming service (seeprivilege specifications in the InputSpecifications for Add and Delete TaskMethods section).Required.The value refers to the RedCarpetemployee for whom the task will be added.Any of the following employee profileattributes are supported: the employeeLogin id, a unique email address, or theprofile authparam. The strForWhomUserparameter will also accept the programgenerated userguidsimple stringsimple stringUser Import and Edit 56

RedCarpetstring strEventNamestrTaskDefinitionStringIdstrSendEmailsRequired.The value refers to the event for which thetask will be added. The event name (in thedefault language) or event code as it isdisplayed on the Administration ->Localization page.Required.A unique identifier for the task as definedin the “Task Definition ID” field on theEdit Task Definition page See InputSpecifications for Add and Delete TaskMethods for additional information.RequiredPossible values are:• True to send notification atask has been added.• False to not send notificationa task has been added.simple stringsimple stringsimple stringMethod ReturnsA sample return is as follows:Error adding task.0ErrorSpecified user's event already has specified task35005The elements of the record returned in the data string are as follows:Element Syntax Value DescriptionDataAddTaskResultsParent node.Parent nodeUser Import and Edit 57

RedCarpetElement Syntax Value DescriptionError Parent node Exists only for a method that fails.The following Error format is returned foreach error that occurs:See next tableSee next table See next tableThe following message and error codes apply to AddTask: ValueValueValueDescriptionErrorErrorErrorErrorErrorUnknown user identifier:{0}The e-mail address used toidentify a user is used bymore than one user{0} event doesn't exist foruser: {1}Unknown event name orcode: xxxUnknown task definitionstring ID: xxx30047 Value passed in the strForWhomUservariable must be a Login ID, emailaddress, valid userguid, or authparam30013 RedCarpet does not enforce unique e-mail address by default. In order to usean email as a unique identifier, the emailmust be unique30014 Specified Event must exist for employeespecified in the strForWhomUser30046 strEventName must contain a valid eventname or code (as displayed on theLocation page)35002 strTaskDefinitionStringID must contain avalid Task Definition ID (as displayed onthe Manage Tasks page)Error I9 tasks cannot be added 35003 I9 Tasks can not be programmaticallyaddedErrorErrorSpecified event definitiondoes not have specifiedtask definitionSpecified user's eventalready has specified task35004 strTaskDefinitionStringID must contain avalid Task Definition ID for the specifiedevent (as displayed on the Manage Taskspage)35005 An existing task can not be added.User Import and Edit 58

RedCarpet ValueValueValueDescriptionError Insufficient privileges 34001 See Input Specifications for Add andDelete Task Methods for session idprivilege criteria.AddTaskEx MethodUsageUsed to programmatically add a dependent task on an existing event for anexisting employee and opting to add the task as either an unassociated task or adependent task.If the added task is a dependent task in the workflow, and the parent task iscurrently an incomplete task, and the parent task is NOT defined as “AlwaysReopen Dependent Tasks”, you must use the AddTaskEx method instead of theAddTask method.Both the AddTask and AddTaskEx methods can handle adding dependent tasks ifthe parent task is defined as “Always Reopen Dependent Tasks”.Code examplesTo add a task with a Task Definition ID of “Transfer_Task1” to an event called“Transfer” for the employee with the loginID of “Jackson.Smith” the examplesyntax is as follows:.strForWhomUser = “Jackson Smith”eprise.epsstringex ret = service.AddTaskEx(sessionnum,strForWhomUser, “Transfer”,“Transfer_Task1”, “true”, “true”);if (ret.errornum != 1){console.out.writeline("error while adding task" + " error:" + ret.data);return;}ParametersstrSecurityTokenRequired.Valid Session ID for consuming service (seeprivilege specifications in the InputSpecifications for Add and Delete TaskMethods section).simple stringUser Import and Edit 59

RedCarpetstrForWhomUserstring strEventNamestrTaskDefinitionStringIdstrSendEmailsstrAddAsDependentTaskEvenIfCanBeIndependentRequired.The value refers to the RedCarpetemployee for whom the task will be added.Any of the following employee profileattributes are supported: the employeeLogin id, a unique email address, or theprofile authparam. The strForWhomUserparameter will also accept the programgenerated userguidRequired.The value refers to the event for which thetask will be added. The event name (in thedefault language) or event code as it isdisplayed on the Administration ->Localization page.Required.A unique identifier for the task as definedin the “Task Definition ID” field on theEdit Task Definition page See InputSpecifications for Add and Delete TaskMethods for additional information.RequiredPossible values are:• true to send notification a taskhas been added.• false to not send notification atask has been added.RequiredSee additional information below.Possible values are:• true to add the task as aninactivate task to be activatedafter the parent is completed• false to add the task as anactivate task unassociatedtask..simple stringsimple stringsimple stringsimple stringsimple stringIf multiple events matching the specifed strEventName exist for the employee, thetask will be added to the (single) “in progress” event. If no “in progress” eventexists, the task will be added to the last completed event. The event will be set to“in progress” (similar to adding a task to a completed event in the user interface).If the added task is a dependent task in the workflow, and the parent task iscurrently an incomplete task, and the parent task is NOT defined as “AlwaysUser Import and Edit 60

RedCarpetReopen Dependent Tasks”, thestrAddAsDependentTaskEvenIfCanBeIndependent parameter signifies:• True to add the task as an inactivate task to be activated after the parent iscompleted.• False to add the task as an activate task unassociated task..Method ReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.Error codes are returned in the same format for the post and the method call.ErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataA record will be returned with descriptive XMLUser Import and Edit 61

RedCarpetA sample return is as follows:Error adding task.0ErrorSpecified user's event already has specified task35005The elements of the record returned in the data string are as follows:Element Syntax Value DescriptionDataAddTaskResultsParent node.Parent nodeError Parent node Exists only for a method that fails.The following Error format is returned foreach error that occurs:See next tableSee next table See next tableThe following message and error codes apply to AddTaskEx: ValueValueValueDescriptionErrorUnknown user identifier:{0}30047 Value passed in the strForWhomUservariable must be a Login ID, emailaddress, valid userguid, or authparamUser Import and Edit 62

RedCarpet ValueValueValueDescriptionErrorErrorErrorErrorThe e-mail address used toidentify a user is used bymore than one user{0} event doesn't exist foruser: {1}Unknown event name orcode: xxxUnknown task definitionstring ID: xxx30013 RedCarpet does not enforce unique e-mail address by default. In order to usean email as a unique identifier, the emailmust be unique30014 Specified Event must exist for employeespecified in the strForWhomUser30046 strEventName must contain a valid eventname or code (as displayed on theLocation page)35002 strTaskDefinitionStringID must contain avalid Task Definition ID (as displayed onthe Manage Tasks page)Error I9 tasks cannot be added 35003 I9 Tasks can not be programmaticallyaddedErrorErrorSpecified event definitiondoes not have specifiedtask definitionSpecified user's eventalready has specified task35004 strTaskDefinitionStringID must contain avalid Task Definition ID for the specifiedevent (as displayed on the Manage Taskspage)35005 An existing task can not be added.Error Insufficient privileges 34001 See Input Specifications for Add andDelete Task Methods for session idprivilege criteria.User Import and Edit 63

RedCarpetDeleteTask MethodUsageUsed to programmatically delete a task from an existing event for an existingemployee.Code examplesTo delete a task with a Task Definition ID of “Transfer_Task1 to an event called“Transfer” for the employee with the loginID of “Jackson.Smith” the examplesyntax is as follows:.strForWhomUser = “Jackson Smith”eprise.epsstringex ret = service.DeleteTask(sessionnum,strForWhomUser, “Transfer”,“Transfer_Task1”, “true”);if (ret.errornum != 1){console.out.writeline("error while adding task" + " error:" + ret.data);return;}ParametersstrSecurityTokenstrForWhomUserstring strEventNameRequired.Valid Session ID for consuming service (seeprivilege specifications in the InputSpecifications for Add and Delete TaskMethods section).Required.Any of the following employee profileattributes are supported: the employeeLogin id, a unique email address, or theprofile authparam. The strForWhomUserparameter will also accept the programgenerated userguidRequired.The event name (in the default language) orevent code as it is displayed on theAdministration -> Localization page.simple stringsimple stringsimple stringUser Import and Edit 64

RedCarpetstrTaskDefinitionStringIdstrSendEmailsstrdontDeleteIfFormExistsRequired.A unique identifier for the task as definedin the “Task Definition ID” field on theEdit Task Definition page See InputSpecifications for Add and Delete TaskMethods for additional information.RequiredPossible values are:• True - to send notification atask has been added.• False - to not send notificationa task has been added.RequiredPossible values are:• True - Task will not be deletedif the task has a form.• False - both the task and formwill be deletedsimple stringsimple stringsimple stringIf multiple events matching the specifed strEventName exist for the employee, thetask will be deleted from the (single) “in progress” event.Method ReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.Error codes are returned in the same format for the post and the method call.ErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedUser Import and Edit 65

RedCarpetDataA record will be returned with descriptive XMLA sample return is as follows:Error adding task.0ErrorSpecified user's event does not have specified task35006User Import and Edit 66

RedCarpetThe elements of the record returned in the data string are as follows:Element Syntax Value DescriptionDataDeleteTaskResultsParent node.Parent nodeError Parent node This node is included only for a method thatfails. The following Error format is returnedfor each error that occurs:See next tableSee next table See next tableThe following message and error codes apply to DeleteTask: ValueValueValueDescriptionErrorErrorErrorErrorErrorUnknown user identifier:{0}The e-mail address used toidentify a user is used bymore than one user{0} event doesn't exist foruser: {1}Unknown event name orcode: xxxUnknown task definitionstring ID: xxx30047 Value passed in the strForWhomUservariable must be a Login ID, emailaddress, valid userguid, or authparam30013 RedCarpet does not enforce unique e-mail address by default. In order to usean email as a unique identifier, the emailmust be unique30014 Specified Event must exist for employeespecified in the strForWhomUser30046 strEventName must contain a valid eventname or code (as displayed on theLocation page)35002 strTaskDefinitionStringID must contain avalid Task Definition ID (as displayed onthe Manage Tasks page)Error I9 tasks cannot be deleted 35000 I9 Tasks can not be programmaticallydeletedUser Import and Edit 67

RedCarpet ValueValueValueDescriptionErrorErrorSpecified event definitiondoes not have specifiedtask definitionSpecified user's event doesnot have specified task35004 strTaskDefinitionStringID must contain avalid Task Definition ID for the specifiedevent (as displayed on the Manage Taskspage)35006 The task must exist to be deleted.Error Insufficient privileges 34001 See Input Specifications for Add andDelete Task Methods for session idprivilege criteria.User Import and Edit 68

RedCarpetGetTasksUsageGetTasks returns task data for all tasks for a specific event name that meet theinput criteria by task status.Addtional input options include criteria to retrieve tasks by:• "ForWhom" employee identifiers (the employee benefitting from the task)information such as employee id, hire date range, key property value• event information such as event Name, event category value, event namedpeople, and event effective date range• task information such as task status by date range, and task definition idThe method returns task data including event name, "ForWhom" employeeidentifiers, task status, task name and definition id, task assignees, task activationdate, task completion date, who completed the task, and task due date.If multiple events were launched for the employee that meet the selection criteria,the method returns the task data for the most recently launched event.The maximum number of tasks returned in each call is 500. A node called“synchronization token” is provided to page through the next set of 500 tasks thatmeet the input criteria.• The synchronization token is an optional input parameter.• The synchronization token is included in the output.On the first call, the synchronization token (which defaults to null), is optionallypassed as null. If your results exceed 500 records, you should call the methodagain passing the returned synchronization token. Subsequent calls will return thenext 500 records.Input for GetTasksstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below.The valid session user must have permissions to view the tasks being requested.Permissions to view a task are granted to users on a team with View All Tasksprivilege.User Import and Edit 69

RedCarpetExamples of GetTasks strXMLExample of GetTasks strXML to return a list of tasks for employees hired within aspecific date range:

RedCarpetNodes in GetTasks strXMLNode Description NotesXML Document headerParent nodeRequired Parent node Optional Parent node OptionalType of ID value beingspecified in nodeOccurs onceUnique identifier ofForWhom employeeValid Values:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIDExample:SSOAuthParamExample:jane.smithOccurs unbounded Parent node. OptionalForWhom employee Hire Date asentered on the EmployeeProfile detail section YYYY-MM-DD format Example:2010-08-28 YYYY-MM-DD format Example:2010-09-28End parent nodeend parent nodeend parent nodeUser Import and Edit 71

RedCarpetNode Description Notes Occurs 1 Required.Valid values:CompleteIncompleteAnd optionally for more granulartypes of Incomplete tasks:InactiveActiveWarningOverdueExample:Inactive Parent node OptionalOccurs UnboundedClose parent nodeSynchronization tokenmarker for where to beginthe results set. Use onlywhen making repeat calls topage through a results setexceeding 500 tasks.A valid synchronizationtoken (generated byRedCarpet and obtained bya previous call to thismethod) returns the next setof up to 500 tasks.close parent nodeSimple string matching the taskdefinition id defined in theRedCarpet User InterfaceOptional.Default is null.Use only when pageing throughresults sets of 500 tasks or more.indicates a null value.The synchronization token is a simplestring and should be stored as a string.User Import and Edit 72

RedCarpetMethod ReturnsAn XML document defined as ]]>ErrorString nodeReturn description of error. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.Error codes and strings are listed below.ErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataNode returned with descriptive XML containing![CDATA[]] if the methodfailed (ErrorNum=0)or if the method succeeded (ErrorNum=1)![CDATA[]]User Import and Edit 73

RedCarpetThe elements of the record returned in the data string are as follows:Element Syntax Value DescriptionDataGetTasksResultsParent node.Parent nodeError Parent node This node is included only for a method thatfails. The following Error format is returnedfor each error that occurs:See next tableSee next table See next tableThe following message and error codes apply to GetTasks: ValueInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputInvalid InputValueInvalid category aliasCode: 'NonExist'Invalid category value codefor X category: Y valueUnknown task definitionstring ID:NonExistantTaskKey Property: Invalidcategory alias Code: XKey Property: Invalidcategory value code forNonExistCatValuecategory: XKey Property: Invalidperson Code: XThe LoginID(NonExistantUser) used toidentify a user is not usedby any known userValue30042300053500239002390103900439011'User Import and Edit 74

RedCarpet ValueInvalid InputInvalid InputValueInvalid input XML:description of invalidelementThe synchronization tokencannot be decrypted andappears to have beentampered with.Value4200042002Sample ReturnsExample return with data:No Error1Onboarding-EVerifyEvent_754c37d74-587e-453a-ae3b97d0981cc9ebCBrown100100100Charlie.Browncharlie.brown@silkroadtech.comOverdueEmployer Views E-Verify StatusHR_REVIEWa0b90424-ad07-41d7-bd97b8ab6f59916b100Amy.HrCoordAmy.HrCoord@mySRT.comSSg9M4zc12PCX35M8d+PuqhZQ2CpleMG8LFDnPHnAfg=]]> User Import and Edit 75

RedCarpetIf an employee is returned all the identifiers are returned for the employee.For example:54c37d74-587e-453a-ae3b97d0981cc9ebCBrown100100100Charlie.Browncharlie.brown@silkroadtech.coma0b90424-ad07-41d7-bd97b8ab6f59916b100Amy.HrCoordAmy.HrCoord@mySRT.coma0b90424-ad07-41d7-bd97b8ab6f59916b100Amy.HrCoordAmy.HrCoord@mySRT.comIf no employee is applicable such as the CompletedByEmployee on tasks notcomplete, the value is The SynchronizationToken is used solely for paging through the results set. Usethe token to tasks for each call that returns 500 tasks. The subsequent call shouldhave the same input parameters with the exception of the new token value. Youshould not modify the value of the synchronization token.SSg9M4zc12PCX35M8d+PuqhZQ2CpleMG8LFDnPHnAfg=User Import and Edit 76

RedCarpetExample return with errors:Invalid input XML: The 'TaskStatus' element is invalid - Thevalue 'Incomp' is invalid according to its datatype 'String' - The Enumerationconstraint failed.0Invalid InputInvalid input XML: The 'TaskStatus' element is invalid - The value'Incomp' is invalid according to its datatype 'String' - The Enumerationconstraint failed.42000]]> User Import and Edit 77

RedCarpetCompleteTaskExUsageCompleteTaskEx completes a specified active task. The task is identified by taskdefinition id for a specific benefiter ("for whom employee”). The input parametersinclude who is completing the task, task notes, and if a notification should be sent.The CompleteTaskEx method does not allow the caller to complete tasks if any ofthe following conditions are true:• if a task is marked as complete with the (associated) form is complete• if a task has a “viewform” instruction with a form associated.• if a task is a parent task (in the task hierarchy) and has an optional formThe output is a success or failure status on completing the task.Input for CompleteTaskExstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below.The valid session user must have permissions to complete the tasks beingrequested. Permissions to view a task are granted to users on a team with View AllTasks privilege.User Import and Edit 78

RedCarpetExamples of CompleteTasksEx strXMLExample of CompleteTasksEx strXML to complete a task with a Task Definition IDof WS_ProvideKeyCard for Charlie.Brown, completed by Amy.Jackson.:Event_7LoginIDCharlie.BrownWS_ProvideKeyCardfalseLoginIDAmy.JacksonNodes in CompleteTaskEx strXMLNode Description NotesXML Document headerRequired Parent node Required Parent node Required Parent node RequiredSimple string. Uniqueidentifer for each event..Event code is defined in theRedCarpet User interface onthe Localizations page.Required Parent node RequiredUser Import and Edit 79

RedCarpetNode Description NotesType of ID value beingspecified in nodeOccurs onceUnique identifier ofForWhom employeeOccurs onceClose Event Parent nodeUnique identifier specifiedon task definition in theRedCarpet user interfaceRequiredValid Values:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIDExample:SSOAuthParamRequiredExample:jane.smithRequiredExample:Close Task Parent nodeIndicates if a completed tasknotification should be sentWelcomeLetter_BostonOptional.Valid Values:truefalseExample:falseSimple string. Text for tasknote.OptionalUser Import and Edit 80

RedCarpetNode Description NotesParent nodeIdentifier of who task iscompleted byType of ID value beingspecified in nodeOccurs onceUnique identifier ofForWhom employeeOccurs onceEnd parent nodeEnd parent nodeOptionalIf CompletedByEmployeeID is notspecified, the task note will indicatethe task was completed by the APIuser (who obtained the session id)RequiredValid Values:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIDExample:SSOAuthParamRequiredExample:jane.smithUser Import and Edit 81

RedCarpetMethod ReturnsAn XML document defined asNo Error1 ]]>ErrorString nodeReturn description of error. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.Error codes and strings are listed below.ErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataNode returned with descriptive XML containing![CDATA[]]]The elements of the record returned in the data string are asfollows:Element Syntax Value DescriptionDataParent node.CompleteTaskExResults Parent node Wrapped in CDATAError Parent node This node is included only for a method thatfails. The following Error format is returnedfor each error that occurs:See next tableSee next table See next tableUser Import and Edit 82

RedCarpetThe following message and error codes apply to CompleteTasksEx: ValueErrorErrorInvalid InputErrorValidation ErrorErrorErrorErrorValueUnknown task definitionstring ID: YUnknown event name orcode: XNo user could be found forthe id:UserItem:LoginID:XUnknown task definitionstring ID: XNot authorized tocomplete the task.Specified user's event doesnot have specified taskYou must be on the formto complete this taskYou must optout of theform to complete this taskValue3500230046310603500235019350063205335024Sample ReturnsExample of the output of a successful call:No Error1 ]]>Example output with an error:Unable to complete task.0User Import and Edit 83

RedCarpetErrorNot authorized to complete the task.35019]]>User Import and Edit 84

RedCarpetChapter 4: Formsand Documents APIForms and Documents APIsRedCarpet web methods provide the following options to accessRedCarpet forms:• retrieve saved forms and completed forms based on variousfilter criteria• retrieve PDF files (populated through RedCarpet)• indicate if a form has already been retrieved• delete existing formsRedCarpet web methods provide an option to retrieve uploadedemployee documents:• retrieve uploaded documents accessible from the EditEmployee tab pagesRetrieve Existing FormsFour web methods are available to retrieve existing forms.Either method can be used to retrieve a list of form id’s that meetspecific criteria.The four methods are very similar to each other with an importantdistinction of the date criteria.• GetFormsIDs and GetFormsIDsEx use the form creation date• GetCompletedForms and GetCompletedFormsEx uses theform completion date• GetCompletedFormsList includes key properties andemployee status.All forms methods allow you to query for forms based on anycombination of the following criteria:• when a form was completed• who the form was completed on behalf of• the type of form (form template name)Web Service 85

RedCarpet• if the form has previously been retrieved• the verification status of a formGetFormsIdsEx and GetCompletedFormsIdsEx methods allow you to query basedon:• what event the form was associated with• what event category values apply to the form benefiterGetCompletedFormsList method allow you to query based on:• Employee Key Properties• Employee Status (Active or Retired)The result of the Forms methods provides a list (table) of unique form ids. Forpurposes of retrieving the actual form, each form id is passed to the GetFormXMLmethod to retrieve the form data.GetFormsIDs and GetCompletedFormsUsage and Parameters of GetFormsIDsRetrieves a list of (saved) form id’s that meet the specified criteria.Parameters for GetFormsIDs GetFormsIDsExand GetCompletedFormsIDsExincludeEventName andCategory values inthe selectioncriteria.strSecurityTokenstrStartingDatestrEndingDatestrLogInIDRequired.Valid Session ID for consuming serviceOptional. Used to specify the start of a daterange. The date range queries the creationdate of saved forms.A string in yyyy-mm-dd format.Optional. Used to specify the end of a daterange. The date range queries the creationdate of saved forms.A string in yyyy-mm-dd format.Optional.RedCarpet LogInID of whom the form wascompleted on behalf of.Specify empty string if you are using theSingle Sign On (“SSO”) authenticationfeature. This parameter is mutuallyexclusive of strFKUserID.simple stringsimple stringsimple stringsimple stringUser Import and Edit 86

RedCarpetstrFKUserIDstrFormTypestrDeliveredOptional.If you are using the Single Sign On toidentify users, this equates to the value in the GetSession requestof whom the form was completed on behalfof.This parameter is mutually exclusive ofstrLogInID. Specify an empty string if youare specifying a value for strLogInID.Optional.Specify a single RedCarpet Form name.Optional.simple stringsimple stringsimple stringA method is outlined below to mark a formas “delivered”. The flag is be used as aselection criteria."" - (empty string) - forms will be returnedregardless of their delivered status.1 - only forms marked as delivered will bereturnedstrVerified0 - only forms not marked as delivered willbe returnedOptional.simple stringA flag can used as a selection criteria.The Verified flag is set to 1 on a task bycompleting a task with the “Check if theform is finished upon task completion.”option checked."" - (empty string) - forms will be returnedregardless of their task completion status.1 - only forms associated with completedtask will be returned0 - only forms associated with incompletetasks will be returnedUser Import and Edit 87

RedCarpetUsage and Parameters of GetCompletedFormsRetrieves a list of completed form id’s that meet the specified criteria.Parameters for GetCompletedFormststrSecurityTokenstrStartingDateRequired.Valid Session ID for consuming serviceOptional. Used to specify the start of a daterange. The date range queries thecompletion date of saved forms.A string in yyyy-mm-dd format.simple stringsimple stringstrEndingDateNote: the results set will return form id’sgreater than the strStartingDateOptional. Used to specify the end of a daterange. The date range queries thecompletion date of saved forms.A string in yyyy-mm-dd format.simple stringstrLoginIDstrFormTypestrDeliveredNote: the results set will return form id’sless than the strEndingDateOptional.RedCarpet LogInID of whom the form wascompleted on behalf of.Specify empty string if you are using theSingle Sign On (“SSO”) authenticationfeature. This parameter is mutuallyexclusive of strFKUserID.Optional.Specify a single RedCarpet Form name.Optional.simple stringsimple stringsimple stringA method is outlined below to mark a formas “delivered”. The flag is be used as aselection criteria."" - (empty string) - forms will be returnedregardless of their delivered status.1 - only forms marked as delivered will bereturned0 - only forms not marked as delivered willbe returnedUser Import and Edit 88

RedCarpetstring strEventNameOptional. Used to specify the event nameassociated with the task for the savedforms."" - (empty string) - forms will be returnedregardless of the event.valid values match the event string asspecified on the Event List underAdministration -> Manage Events page inthe RedCarpet user interface.simple stringInput for GetCompletedFormsListRetrieves a list of completed form id’s that meet the specified criteria.If no forms meet this specified filter critera, no form IDs will be returned.Parameters for GetCompletedFormsListstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below. The XMLspecifies the document criteria for selection.Input for GetCompletedFormsListstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below. The XMLspecifies the document criteria for selection.Nodes in GetCompletedFormsList strXMLNode Description NotesXML Document headerRequiredUser Import and Edit 89

RedCarpetNode Description Notes Parent nodeOptionalOccurs once.Optional - date range ofuploadOccurs once.OptionalEmployeeIDType and IDoccurs for as manyEmployee ID as to bereturnd, (see example below)Expect values:“1” for delivered“0” for not deliveredIf CompletionDateRange is specifiedboth Begin Date and End Date must bespecified.Fomat is YYYY-MM-DDPossible values for EmployeeIDTypeare:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIUser Import and Edit 90

RedCarpetNode Description Notes Optional Occursonce per request. Childnodes occur multiple time asapplicable to the employeedefinition.Possible values for EmployeeIDTypeare:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIDate format is YYYY-MM-DDDateCode and PersonCode are specifiedas they are defined in Key Properties.

RedCarpetNode Description NotesOptional.FormType can occur manytimes per callFormType values match the Form namedefined in RedCarpet. Optionalclose parent nodeSample strXMLThe following strXML returns all the forms not yet delivered completed between11-15-2012 and 12-15-2012:02012-11-152012-12-15User Import and Edit 92

RedCarpetGetCompletedFormsList ReturnsEach method returns an XML document of the following structure: ErrorString and Error NumThe value of ErrorNum should be checked for a the value not equal to 1 todetermine an error description vs. a success message.ErrorNum indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedIf the ErrorNum returns a 1 the ErrorString is equal to “No Errors”.If the ErrorNum returns a value not equal to 1 the ErrorString is equal to “Therewere errors” or an error message. Errors are described in the Data string.DataAn XML record describing either the successful task data or a detail of thereason for failure.The Data record xml is returned as CDATA tag.If one or more parameters are in error, the ErrorNum returns a value not equalto 1. The XML in the Data string will describe the errors. The error text in thedata string and error codes are described in the “Method Returns” section ofeach method description.FormID is in a column called “ObjectId” Note: See also -Sample CodeExample at theend of thisdocument.Code examplesTo return all existing forms:Eprise.EpsTableEx t = service.GetFormsIDs(sessionnum,"","","","","","","")To return all forms for the user “Jim.Smith”:Eprise.EpsTableEx t = service.GetFormsIDs(sessionnum,"","","Jim.Smith","","","","")User Import and Edit 93

RedCarpetTo return all completed existing “I-9” forms:Eprise.EpsTableEx t = service.GetCompletedForms(sessionnum,"","","","I-9","","")Sample Return DataAn example return is as follows:User Import and Edit 94

RedCarpetUser Import and Edit 95

RedCarpet1ObjectIdForm_TypeOwnerCompletedDateDeliveredNameEventID5684Parking_Assignement_Form1f80999e-d539-4fca-9e1a9ce8642750232009-06-18Onboarding495685Form_I_9_20091f80999e-d539-4fca-9e1a9ce864275023Onboarding495686Confidentiality_Agreement1f80999e-d539-4fca-9e1a9ce864275023Onboarding49User Import and Edit 96

RedCarpetSample return data for GetCompletedFormsListNo Error112845Form_I_9_20098e1e0acb-1e46-4d65-9f5e81f71a7637271000Mark.Smithmsmith@MySRT.com2012-12-0532Event_7Onboarding-EVerify12852Form_I_9_2009c685464d-7055-4c77-9dccbf42361b3aa43001User Import and Edit 97

RedCarpetwes.rogerswrogers@MySRT.com2012-12-0635Event_7Onboarding-EVerify]]>GetFormsIDsEx and GetCompletedFormsIDsExUsageRetrieves a list of (saved) form id’s that meet the specified filter criteria includingevent name and category values.• Use GetFormsIDsEx to retrieve saved Form IDs by creation date• Use GetCompletedFormsIDsEx to retrieve completed Form IDs by completiondateSyntax of the Category ParameterGetFormsIDsEx and GetCompletedFormsIDsEx allow for an optional inputparameter of category values as a filter criteria for the results set. Categoriesdefined in your implementation of RedCarpet are customized for your company.The values are determined by your implementation.Categories have multiple uses in RedCarpet. In the context of forms, you may filteron event categories to retrieve specific categories of forms. The event categoryvalues selected for the launched event will be associated with the forms generatedfor the event’s tasks.An array of array of strings are used to pass the name / value pairs for eachcategory to be used in the filter. The array of strings contains 2 elements:1 Alias (Category) name. The string should be specified as defined in theManage Event page visible in the RedCarpet user interface.User Import and Edit 98

RedCarpet2 Unique (category) value. The string should be specified as defined in theManage Hierarchical Category Values page in the in RedCarpet userinterface. The unique value can be specified in one of three formats.• by name• by internal code• by path in the hierarchical treeUse one of these three values, whichever is most convenient to yourconfiguration. The method you use must result in a unique value. If you have ajob type category value such as “Staff’ that exists under Exempt\Staff andNon-Exempt\Staff you may not reference “Staff” by name. You may use thepath to reference the value.The path (hierarchical tree) notation uses backslashes “\\” to note the node.The format type is not specified. A unique value is the only criteria.String[][] arrCategory = new String[3][];arrCategory[0] = new String[]{"Location","Boston"};name.// Specifies aarrCategory[1] = new String[]{"Department", "CS_BLDNG_5"};// Specifies a code, not a name.arrCategory[2] = new String[]{"Job Type", "\\Exempt\\Staff"};// backslashes, including leading \ to note pathParameters for GetFormsIDsExstrSecurityTokenstrStartingDatestrEndingDatestrLogInIDRequired.Valid Session ID for consuming serviceOptional. Used to specify the start of a daterange. The date range queries the creationdate of saved forms.A string in yyyy-mm-dd format.Optional. Used to specify the end of a daterange. The date range queries the creationdate of saved forms.A string in yyyy-mm-dd format.Optional.RedCarpet LogInID or user GUID ofwhom the form was completed.Specify empty string if you are using theSingle Sign On (“SSO”) authenticationfeature. This parameter is mutuallyexclusive of strFKUserID.simple stringsimple stringsimple stringsimple stringUser Import and Edit 99

RedCarpetstrFKUserIDstrFormTypestrDeliveredstrVerifiedOptional.If you are using the Single Sign On toidentify users, this equates to the value in the GetSession requestof whom the form was completed on behalfof.This parameter is mutually exclusive ofstrLogInID. Specify an empty string if youare specifying a value for strLogInID.Optional.Specify a single RedCarpet Form name.Optional.A method is outlined below to mark a formas “delivered”. The flag is be used as aselection criteria."" - (empty string) - forms will be returnedregardless of their delivered status.1 - only forms marked as delivered will bereturned0 - only forms not marked as delivered willbe returnedOptional.A flag can used as a selection criteria.simple stringsimple stringsimple stringsimple stringstrEventNameThe Verified flag is set to 1 on a task bycompleting a task with the “Check if theform is finished upon task completion.”option checked."" - (empty string) - forms will be returnedregardless of their task completion status.1 - only forms associated with completedtask will be returned0 - only forms associated with incompletetasks will be returnedOptional. Used to specify the event nameassociated with the task for the savedforms."" - (empty string) - forms will be returnedregardless of the event.valid values match the event string asspecified on the Event List underAdministration -> Manage Events page inthe RedCarpet user interface.simple stringUser Import and Edit 100

RedCarpetarrCategoryFilterOptional. Used to specify the benefiter’scategory values associated with the savedforms."" - (empty string) - forms will be returnedregardless of the associated categories.valid values match the strings as specifiedon the Manage Hierarchical CategoryValues under Administration -> ManageCategories page in the RedCarpet userinterface. See “Syntax of the CategoryParameter” on page 98ArrayOfArrayOfStringParameters for GetCompletedFormsIDsExstrSecurityTokenRequired.simple stringstrStartingDatestrEndingDatestrLogInIDstrFKUserIDstrFormTypeValid Session ID for consuming serviceOptional. Used to specify the start of a daterange. The date range queries thecompletion date of saved forms.A string in yyyy-mm-dd format.Optional. Used to specify the end of a daterange. The date range queries thecompletion date of saved forms.A string in yyyy-mm-dd format.Optional.RedCarpet LogInID or user GUID ofwhom the form was completed .Specify empty string if you are using theSingle Sign On (“SSO”) authenticationfeature. This parameter is mutuallyexclusive of strFKUserID.Optional.If you are using the Single Sign On toidentify users, this equates to the value in the GetSession requestof whom the form was completed.This parameter is mutually exclusive ofstrLogInID. Specify an empty string if youare specifying a value for strLogInID.Optional.Specify a single RedCarpet Form name.simple stringsimple stringsimple stringsimple stringsimple stringUser Import and Edit 101

RedCarpetstrDeliveredstrEventNamearrCategoryFilterOptional.A method is outlined below to mark a formas “delivered”. The flag is be used as aselection criteria."" - (empty string) - forms will be returnedregardless of their delivered status.1 - only forms marked as delivered will bereturned0 - only forms not marked as delivered willbe returnedOptional. Used to specify the event nameassociated with the task for the savedforms."" - (empty string) - forms will be returnedregardless of the event.valid values match the event string asspecified on the Event List underAdministration -> Manage Events page inthe RedCarpet user interface.Optional. Used to specify the benefiter’scategory values associated with the savedforms."" - (empty string) - forms will be returnedregardless of the associated categories.valid values match the strings as specifiedon the Manage Hierarchical CategoryValues under Administration -> ManageCategories page in the RedCarpet userinterface. See “Syntax of the CategoryParameter” on page 98simple stringsimple stringArrayOfArrayOfStringReturnsA table of type EpsTableEx.The structure is:EpsTableEx{String ErrorString;int ErrorNum;String[][] Data;}ErrorStringUser Import and Edit 102

RedCarpetReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code description return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedUser Import and Edit 103

RedCarpetDataA string array containing columns and their corresponding values. Therequested FormID is returned as ObjectId.Sample output is as follows:1ObjectIdForm_TypeOwnerCompletedDateDeliveredNameEventID10544Form_I_9_2009eace7ee3-d566-432f-b32fe0fa48ce1df32011-06-21Onboarding-Short85Code examplesTo return all existing forms for the category “Old Department” with a value ofMarketingString[][] arrCats = new String[1][];arrCats[0] = new String[]{"Old Department","\\All Departments\\Marketing"};EpsTableEx tRet = service.GetFormsIDsEx(sessionnum, "", "", "", "", "", "", "",arrCats);To return all the forms for the employee jane.johnson:EpsTableEx tRet = service.GetFormsIDsEx(sessionnum, "", "", "jane.johnson", "", "","", "", "");User Import and Edit 104

RedCarpetTo return all the completed forms for employee jane.johnson:EpsTableEx tRet = service.GetCompletedFormsIDsEx(sessionnum, "", "","jane.johnson", "", "", "", "", "");GetFormXMLUsageRetrieves an existing XML form based on the specified FormID.Parameters for GetFormXMLstrSecurityTokenRequired.simple stringstrFormIDValid Session ID for consuming serviceRequired.simple stringA single formID . FormID is returned byGetFormsIDs, GetFormsIDsEX orGetCompletedFormsIDEx method asReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedUser Import and Edit 105

RedCarpetDataA string containing the XML of the requested FormIDSample output of the Data string (“ret.Data”) for a form named TEST_W4with five fields named SSN, City, State, Zip, and DT_NOW is asfollows:123-456-789ClintonMA015102006-08-02Code examplesTo return XML of the GetFormIDs method and write the output a file:User Import and Edit 106

RedCarpetEprise.EpsStringEx ret = service.GetFormXML(sessionnum,t.Data[i][nObjectid]);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to retrieve xml for " +t.Data[i][nObjectid] + " Error:" + t.ErrorString);return;}String strXML = ret.Data;String strFileName =String.Format("c:\\downloadedforms\\Form{0}.xml",t.Data[i][nObjectid]);FileStream f = File.OpenWrite(strFileName);Byte [] arrBytes = ue.GetBytes(strXML);f.Write(arrBytes,0,arrBytes.Length);f.Close();To return XML of the FormID “9678”:Eprise.EpsStringEx ret = service.GetFormXML(sessionnum,”9678”;User Import and Edit 107

RedCarpetMark a Form as DeliveredA delivery status flag is available to be set based on the processing specificationsof your e-forms.UsageUsed to indicate the delivery status of a form based on the FormID.ParametersstrSecurityTokenRequired.Valid Session ID for consuming servicesimple stringNote: After the formdelivery status hasbeen set tocompleted, thetask associatedwith the form cannot be reopened.strFormIDRequired.simple stringA single formIDstrDeliveredUse:simple string0 - to set a form delivery status toundelivered. After a form is completed thedelivered state is set to 0.1 - to set a form to delivery status todelivered. By default, delivered is alsolocked. The associated task can not bereopened and no form updates are allowed.2- to set a form to delivery status todelivered and unlocked. Unlocked formsallow the task owner to reopen theassociated task and update the form.After processing a form, if you choose to set the delivery status to “1”, the task withthe associated e-form can not be reopened. This functionality is to insure the datais not updated after an e-form is delivered to the external application.User Import and Edit 108

RedCarpetIf the task is attempted to be reopened the follwoing message is displayed.After processing a form, if you choose to set the delivery status to “2”, the task withthe associated e-form can be reopened and the form can be updated. If the systemaccepting the forms data is intelligent to process duplicates, this is therecommended technique. For example Jane Doe completes a form. Yourintegration logic retrieves the completed form and updates your external system. IfJane later updates the form, the delivered state will be set back to 0 (zero). if youwant the updated information to be updated to your external system, you shoulduse this setting. This functionality is to insure form data can be updated after it isdelivered.Based on the requirements of the dependent application for e-form data changingafter it has been delivered, you may choose to implement functionality to (re)setthe strDelivered flag status to incomplete for specific situations.It is not valid to change the strDelivered flag status from “1” (delivered / locked) to“2” (delivered / unlocked).• A valid state transition for the strDelivered flag is “1” (delivered / locked) to“0” (undelivered).• A valid state transition for the strDelivered flag is “0” (undelivered) to “2”(delivered / unlocked).This is important if you have forms in a locked status that you want to unlock. Youmust reset the status to “0” before setting it to “2”.Special Processing for Unlocked I-9 Form DataE-Verify is very specific with it’s rules regarding one active E-Verify case peremployee. RedCarpet has multiple checks to prevent an employer from openingmulitple E-Verify cases at the same time. In support of this, updating I-9 Form datathat is associated with an E-Verify case, by default is not permitted. The defaultbehavior is to disallow re-opening a closed E-Verify submission task.Procedure for updating I-9 forms after they have been marked as delivered to anexternal system.User Import and Edit 109

RedCarpetIn 2.7.x the process flow (for an I-9 form) is:1 Form is created via step 1 task. It is editable only by the benefiter of the event.2 Form is updated via a step 2 task. It is editable by the task owner or I-9 admin.Form is completed and step 2 task is completed.3 Form data is fed to E-verify submission screen. Step 3 task is completedwhen E-Verify case is closed.4 Closed step 3 tasks (step 2 and step 1) tasks cannot be reopened.5 Form is selected, form data is retrieved and passed to external system6 Form is marked as delivered by calling MarkFormAsDelivered (FormID, 1). 1notes delivered and locked.7 No I-9 task can be reopened for a locked form. No form updates are allowed.In 2.8x the process flow (for an editable closed I-9 form) is:1 Request your configuration be upgraded to allow for a step 1 or step 2 task tobe opened without affecting the other tasks in the workflow.• Set "Enable Always Reopen Dependent Tasks checkbox for I-9 Step 1and 2 task definitions" to On.• Recycle• Edit the step 1 and 2 task definitions to uncheck the "Always ReopenDependent Tasks" checkbox.• Confirm you have selected “Restrict re-opening of task to EventCoordinator:”2 For new employees launched:• Form is created via step 1 task. It is editable only by the benefiter of theevent.• Form is updated via a step 2 task. It is editable by the task owner or I-9admin. Form is completed and step 2 task is completed.• Form data is fed to E-verify submission screen. Step 3 task is completedwhen E-Verify case is closed.• Closed step 3 tasks (step 2 and step 1) tasks are now allowed to bereopened (independently of each other).3 I-9 Forms are selected, form data is retrieved (and used to update yourexternal system)4 Form is marked as delivered by calling MarkFormAsDelivered (FormID, “2”). 2notes delivered and unlocked.5 I-9 tasks can be reopened for a unlocked form.• Section 1 can be updated via step 1 task. It is editable only by an I-9Administrator or the benefiter once it is reopened.• Section 2 can be updated via step 2 task. It is editable by the task owneror I-9 admin. Form is completed and step 2 task is completed.User Import and Edit 110

RedCarpet• Step 2 task continues to be completed via "Complete & E-Verify" button.The form will not be submitted to E-Verify again. It simply redisplaysthe e-verify status.In 2.8x the process flow (for an I-9 form completed in RC 2.7.x)is:1 Request to configure the instance of RedCarpet to allow for a step 1 or step 2task to be opened without affecting the other tasks in the workflow.2 Set "Enable Always Reopen Dependent Tasks checkbox for I-9 Step 1 and 2task definitions" to On.3 Edit the step 1 and 2 task definitions to uncheck the "Always ReopenDependent Tasks" checkbox4 Form was marked as delivered by calling MarkFormAsDelivered (FormID, “1”)during the 2.7.x cycle. It is now delivered / locked.5 Reset the form to unlocked using:NOTE: If a form is currently marked as delivered, it must be reset to undeliveredbefore it can be unlocked.• Form is reset by marking the form as undelivered by callingMarkFormAsDelivered (FormID, “0”). “0” notes undelivered.• Form is marked as delivered but unlocked by callingMarkFormAsDelivered (FormID, “2”). “2” set the form to delivered andunlocked.6 I-9 tasks can be reopened for a unlocked form.• Section 1 can be updated via step 1 task. It is editable only by an I-9Administrator or benefiter once it is reopened.• Section 2 can be updated via step 2 task. It is editable by the task owneror I-9 admin. Form is completed and step 2 task is completed.• Step 2 task continues to be completed via "Complete & E-Verify" button.The form will not be submitted to E-Verify again. It simply redisplaysthe e-verify status.• On completing the form the delivery status is set to “0” (undelivered).NOTE: task notes are updated to state the task was re-opend and closed. Werecommend you update the "margin notes" text box on the I-9 form as well as addappropriate task notes.All versions of the I-9 form are available via the auditor's portal.ReturnsA table of type EpsStringEx.The structure is:User Import and Edit 111

RedCarpetEpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataEmpty stringCode examplesTo set the delivery status of an e-form to “delivered” and check the error status:Eprise.EpsStringEx ret =service.MarkFormDelivered(sessionnum,t.Data[i][nObjectid],"1");if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to mark form " + t.Data[i][nObjectid]+ " Error:" + t.ErrorString);return;}Retrieve Populated PDF FilesRedCarpet forms can optionally be designed to merge the form data to an existingPDF file format.Forms that have been configured with the corresponding PDF field mappings canbe requested as a binary return format instead of a text (XML formatted) string.User Import and Edit 112

RedCarpetGetFormPDFUsageUsed to request form data be returned as a PDF file. The form data is merged witha (pre-configured) PDF file based on the FormID.The user obtaining the session id must be able to access both the form and thetask (the form is associated with). The programmatic user will require ‘View AllTasks’ and ‘Manage Forms’ permissionParameters Note: Theconfiguration offorms to map datato a designatedPDF file is aservice providedby SilkRoadSupport.strSecurityTokenRequired.simple stringstrFormIDValid Session ID for consuming serviceRequired.simple stringA single formIDReturnsA table of type EpsBinaryEx.The structure is:EpsBinaryEx{String ErrorString;int ErrorNum;Byte[] Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDatabinary data (PDF binary)User Import and Edit 113

RedCarpetCode exampleRetrieve the corresponding PDF based on the given FormID. Write the PDF to a“downloadedforms” directory:Eprise.EpsBinaryEx ret = service.GetFormPDF(sessionnum,t.Data[i][nObjectid]);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to retrieve pdf for " +t.Data[i][nObjectid] + " Error:" + t.ErrorString);return;}Byte[] arrBytes = ret.Data;String strFileName =String.Format("c:\\downloadedforms\\Form{0}.pdf",t.Data[i][nObjectid]);FileStream f = File.OpenWrite(strFileName);f.Write(arrBytes,0,arrBytes.Length);f.Close();Delete Specified FormA delete method is provided for responsible management of your forms based onyour specifications.DeleteFormUsageUsed to delete a form from RedCarpet based on a FormID.User Import and Edit 114

RedCarpetParametersstrSecurityTokenRequired.simple stringstrFormIDValid Session ID for consuming serviceRequired.simple stringA single formIDReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue of less than 1, for an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataEmpty stringUser Import and Edit 115

RedCarpetCode exampleTo delete a specified RedCarpet form:Eprise.EpsStringEx ret = service.DeleteForm(sessionnum,t.Data[i][nObjectid]);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to delete " + t.Data[i][nObjectid] + "Error:" + t.ErrorString);return;}GetUploadedDocumentListUsageGetUploadedDocumentList returns a list of document id’s. Documents returnedinclude supporting documents uploaded for I-9’s, employee documents (uploadedby the employee through the portal) and documents uploaded by the employerthrough the documents tab. The document id list is created based on the specifiedsearch criteria.If search criteria is specified that does not match any data, no data is returned.The document id list can be used as input to the GetUploadedDocument methodwith returns the binary data of the document.Input for GetUploadedDocumentListstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below. The XMLspecifies the document criteria for selection.Nodes in GetUploadedDocumentList strXMLNode Description NotesXML Document headerRequiredUser Import and Edit 116

RedCarpetNode Description Notes Parent nodeOptional - date range ofuploadOccurs once.OptionalEmployeeIDType and IDoccurs for as manyEmployee ID as to bereturnd, (see example below)Begin Date and / or End Date can bespecified.Fomat is YYYY-MM-DDPossible values for EmployeeIDTypeare:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIUser Import and Edit 117

RedCarpetNode Description Notes Optional Occursonce per request. Childnodes occur multiple time asapplicable to the employeedefinition.Possible values for EmployeeIDTypeare:Employee_HRISIDLoginIDSSOAuthParamEmailGuidLifeSuiteIDate format is YYYY-MM-DDDateCode and PersonCode are specifiedas they are defined in Key Properties.Optional.DocumentType values are::Document TypeFilter occursonce per callDocumentUploadEmployeeDocumentUploadI9UploadUser Import and Edit 118

RedCarpetNode Description Notesclose parent nodeSample strXMLTo get all uploaded documents:DocumentUploadTo get all documents uploaded in support of I-9s by begin and end date2010-11-042012-11-04I9UploadTo get all documents uploaded in support of I-9s by end date2012-12-01User Import and Edit 119

RedCarpetI9UploadTo get all documents for multiple users by user GUID:Guidc3c012fb-b2db-4f13-aafd2ac3d08369aee82bb984-79c5-4de3-adbab5bf4c53faf7ReturnsAn XML Document.The structure is:No Error1ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue of less than 1, for an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataString containing CDATA with PageID as described belowUser Import and Edit 120

RedCarpetSample OutputThe following sample output returns two uploaded documents:No Error15416bafd-615c-43dc-bfd000bbbc77a2edjpgI9Upload240f972f-3349-406f-94866b20d1ea8f253004Dan.connollydconnolly@mysrt.comabe67439-26d6-4246-82cb0331a546883apdfI9Upload56e6f1f7-aab1-43ca-9c5900c2b95d70871001Tammy.Jonestjones@MySRT.comUser Import and Edit 121

RedCarpet]]>GetUploadedDocumentUsageSimilar to the GetFormPDF method, this method returns the binary data for thespecified uploaded document. It is used in conjunction withGetUploadedDocumentList (above).Input for GetUploadedDocumentListstrSecurityTokenRequired.simple stringstrPageIDValid Session ID for consuming serviceRequiredsimple stringpage Id returned byGetUploadedDocumentList .ReturnsAn XML Document.The structure is:No Error1ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue of less than 1, for an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeededUser Import and Edit 122

RedCarpet0 (zero) — method failedDataBinary content for the specified uploaded document.User Import and Edit 123

RedCarpetChapter 5: CategoryUploadOverviewThe Category Upload API allows a import and edit of the categoryvalues.The XML syntax for creating and modifying category values isdocumented in a separate document called the Category UploadGuide (named “RCCategoryImport.pdf”). The Category UploadGuide describes the syntax and available operations to add andmodify the category hierarchy. It also includes a description oftwo support features (Export and Restore Points) available tosupport category hierarchy changes.Category UploadAn XML record used to create and edit category values.CategoryUploadUsageUsed to programmatically create or modify the category valuehierarchy using an XML.This web method does not run an initial validation pass on theXML.Web Service 124

RedCarpetParametersstrSecurityTokenRequired.simple stringcategoryXmluploadFileNameValid Session ID for consuming serviceXML record formatted as described inChapter 2 of the Category Upload Guide.(separate from this document)Not applicable.stringsimple stringExpect value is ““ (empty string).ReturnsThe Data property of the StringEx returned by the web method will contain an XMLstring containing the results of the transaction, including number of CategoryValues affected and, in case of failure, a list of errors that caused the transaction toterminate.A table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataString containing XML record with error descriptionUser Import and Edit 125

RedCarpetCode examplesTo import new RedCarpet users from an XML record.string scategoryXml = “

RedCarpetInput structure doesn't match database structure for Location36002Upload finishedRoot nodes of the response XML will be named based on the Upload operation asfollows:Import = ImportCategoryValuesResultsUpdate = UpdateCategoryValuesResultsUpdateCodes = UpdateCodesResultsReplace = ReplaceCategoyValuesResultsReplaceAll = ReplaceAllResultsBulk Import Error CodesThe following table contains the possible error codes:ValueValueFailed to create restore point. 36000'Code' node doesn't exist for Input structure doesn't match databasestructure for 3600136002Code is too long for {0} 36003Malformed category upload XML 36004Category Value with code '' doesn'texist.Code must be specified to retire Category Value''3600536006Invalid Portal Role: ' 36007User Import and Edit 127

RedCarpetValue'Update' and 'Replace' require all CategoryValue Codes to be populated and are notsupported in your environment. Please use'ReplaceAll' to bulk update your categoryvalues'': only one root CategoryValue is allowed per CategoryInternal Code '' already exists. InternalCodes must be unique if specified.A Category with the name ''already existsValue36008360093601036011Category '' does not exist. 36012User Import and Edit 128

RedCarpetOverviewTwo API’s are available to execute the RedCarpet Events report.GetEventReportEx (released with RedCarpet 2.9.0) andGetEventReport (depreciated with the release ofGetEventReportEx).GetEventReportExUsageUsed to generate XML output using the same parametersavailable in the RedCarpet user interface.The columns included in the report output are specified in theRedCarpet user interface Settings page.Parameters for GetEventReportExstrSecurityTokenRequired.simple stringstrXMLValid Session ID for consuming serviceRequiredsimple stringXML is described below.Web Service 129

RedCarpetExample Structure of GetEventReportEx strXMLOnboardingLocationBOSComplete2013-01-012013-07-02Nodes in GetEventReportExNode Description NotesXML Document headerRequired Parent node RequiredParent node. Optional(minOccurs = 0,maxOccurs = 1)Required for anyEvent FilterOnboarding Optional Exist only if a EventName isspecifiedWeb Service 130

RedCarpetNode Description NotesRequired if isspecified.(minOccurs = 1,maxOccurs = 1)Valid values include categoryname (valid values are thoseavailable in the categoryexport)LocationRequired if isspecified.(minOccurs = 1,maxOccurs = 1)Required if isspecified.Valid values include both full valuepath or value codeLOC_BOSThe code value must match avalue in the Category Export.Required if isspecified.Optional(minOccurs = 0,maxOccurs = 1)Valid Values:InProgress, Complete,CancelledExample:CompleteOptional((minOccurs = 0,maxOccurs = 1)Valid types: Effective(default),Activation, Create, Due, Completed,HireDate)Example:Web Service 131

RedCarpetNode Description NotesOptional.(minOccurs = 0,maxOccurs = 1)If BeginDate is not specifiedit will default to yesterday.YYYY-MM-DD formatExample:Optional.(minOccurs = 0,maxOccurs = 1)2013-06-02If EndDate is not specifiedit will default to today.YYYY-MM-DD formatExample:2013-07-02 close node Required close node RequiredWeb Service 132

RedCarpetReturnsAn XML document defined as:No Error112/1/2012 12:00:00AM12/4/2012 2:24:37 PM12/5/2012 10:43:10 AMCompletemsmith@MySRT.com12/1/2012 12:00:00 AMActiveMarkSmith]]>ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code description return code descriptionErrorNumThis variable indicates success or failure. Values are:1 (one) — method succeeded0 (zero) — method failedDataAn xml document with event data. Event data includes the fields defined inyour configuration. By default the fields are: EventCreationDate, EffectiveDate,EventCompletionDate, EventStatus, EmployeeAuthParam,EmployeeHireDate, EmployeeTerminationDate, EmployeeEmail,EmployeeStatus, EmployeeFirstName, and EmployeeLastName.Note on returned categories: If you configure category to be returned, and thecategories were defined with special characters not accepted for XML nodenames, RedCarpet will replace the special character with an _ (underbar). Ifthe replacement results in a non-unique category name a number will beappended to the category name.Web Service 133

RedCarpetFor customers with a high volume of events SilkRoad does not recommendusing the GetEventReport or GeEventReportEx methods to obtain employeeuser profile and task data information. See GetUserIDList, GetUserProfileEx2and GetTask methods for additional information.GetEventReportUsageUsed to generate XML output using the same parameters available in theRedCarpet user interface.The columns included in the report output are specified in the RedCarpet userinterface Settings page.ParametersPlease note the strStartingDate and strEndingDate parameters have a defaultvalue to limit the data being returned.strSecurityTokenRequired.simple stringValid Session ID for consuming serviceincludes the Reports privilegestrEventName Optional. simple stringarrCategoryFilterOptionalUsed to specify the benefiter’s categoryvalues associated with the event.stringArrayOfArrayOfString"" - (empty string) - all categories will bereturned .valid values match the strings as specifiedon the Manage Hierarchical CategoryValues under Administration -> ManageCategories page in the RedCarpet userinterface. See “Syntax of the CategoryParameter” on page 98.Web Service 134

RedCarpetstrStartingDateOptionalstringOptional. Used to specify the start of a daterange. The date range queries the effectivedate of the event.If srtStartingDate is not specified it willdefaul to yesterday.StrEndingDateA string in yyyy-mm-dd format.OptionalstringOptional. Used to specify the end of a daterange. The date range queries the effectivedate of the event.If srtEndingDate is not specified it willdefaul to todayA string in yyyy-mm-dd format.ReturnsA table of type EpsStringEx.The structure is:EpsStringEx{String ErrorString;int ErrorNum;String Data;}ErrorStringReturn code description. The value of ErrorNum should be checked for a thevalue not equal to 1 to determine an error description vs. a success message.““ or “xxxx” — return code descriptionErrorNumThis variable indicates success or failure. Values are:Data1 (one) — method succeeded0 (zero) — method failedWeb Service 135

RedCarpetString containing XML record with error descriptionCode examplesTo import new RedCarpet users from an XML record.Eprise.EpsStringEx ret = service.GetEventReport(sessionnum,”Onboarding”,,,);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while execute Event Report" + " Error:" +ret.ErrorString);return;}The ret.Data string contains the xml ouptut as is available in the RedCarpet userinterface packaged into a CDATA string.Sample return (with the ret.Data string) is a follows:No Error1Nathan TownsendNathan.TownsendOnboarding18ActiveRC2 HRCoordHR Coordinator1146710Send Welcome LetterSWL1311

RedCarpetCompletionDate>RC2 HRCoordHR CoordinatorsRC2 HRCoord ...]]>Web Service 137

RedCarpetChapter 7: UsingTransformationsOverviewRedCarpet methods allow you to use XSLTs to transform boththe input and the output of many RedCarpet methods.Transforming the XML from one format to another is useful forchanging export from one system to the expected the inputformat of a RedCarpet method. RedCarpet allows atransformation of the output to another format for ease of use forconsumption of the output to another system.SilkRoad also uses the output XLSTs to maintain backwardcompatibility with previous versions of the RedCarpet methods.Manage TransformationsUsageThe Manage Transformations page is available through theRedCarpet user interface. The manage page allows you toupload XSLT files into the RedCarpet database. Uploaded filesare available to be referenced by the method call either byoperation or by reference.RedCarpet administrators with the “Manage Transformation”privilege have access the “Manage Transformations”Administration menu option.Defined transformations are applied based on reference byname, each time an operation (method) is executed, or based onwhich user is executing the method.Default ConfigurationRedCarpet version 2.8.0 introduced the first set of updates toexisting method outputs. The updates are in response tocustomer requests to include more information on the successfulrecords for bulk operations.By default, the output of the method will match the 2.7.x output.The default behavior does not change to insure systemintegrations with RedCarpet will work after upgrading to versionsof RedCarpet after 2.7.x.Web Service 138

RedCarpetFor customers to take advantage of updates to the output you must modify thetransformation definition to remove the transformation of 2.8.0 output to 2.7.xoutput.If an XSLT is managed by Operation, each time the operation is executed theXSLT will be applied. For example, after upgrade to 2.8.0 each timeBulkUserUpload, LaunchEvent, or Update Event is executed the defaulttransformation is applied to remove 2.8.0 nodes from the output.To take advantage of 2.8.0 output, you should modify the XLSTs from the defaultoperation. The recommended technique to do this is to edit the managetransformation criteria to reference the XSLT by name instead of operation.• defining the XSLT by operation applies the XSLT each time the method isexecuted• defining the XLST by name applies the XSLT only when the XML (passed asan input parameter) includes the nodeWeb Service 139

RedCarpetMethods Supporting TransformationsThe following RedCarpet methods support input and output transformations. Inputtransformations expect the resulting transformation to result in the an XMLdocument that matches the method XSD.• BulkUserUpload• XMLUserEdit• LaunchEvent• UpdateEvent• CategoryUpload• GetUserIDList• GetUserProfileEX2• GetCompletedFormsList• GetUploadedDocumentList• ReopenTask• GetFormXMLEx• FieldValueUploadRules for Applying Transformations1 Each transformation allows for new optional property called Operation. Thismay be set to the name of one of a list of supported web methods, if needed.In 2.8.0, the list of supported methods are available. The supported methodsare BulkUserUpload, XmluserEdit, LaunchEvent, UpdateEvent, andCategoryUpload.• GetFormXmlEx allows for an additional optional property called FormType. Form type allows you to specify a transformation per form.2 When handling all new API operations, RedCarpet shall determine whether ornot to use a transformation and which one to use based on the following rules:• If a Transformation name specified in a node in the input XML,• RedCarpet shall search for the transformations matching thatname, and any of Operation (the web method being handled) orLogged in user• RedCarpet shall use the transformation that matches most criteria(Operation AND Logged in user, followed by only Logged in user,followed by only Operation).• If no Transformation name specified in a node in the input XML,• RedCarpet shall search for the transformations matching any ofOperation (the web method being handled) or Logged in user.Web Service 140

RedCarpet• RedCarpet shall use the transformation that matches most criteria(Operation AND Logged in user, followed by only Logged in user,followed by only Operation).• When GetFormXmlEx is the web method being handled, wheneverRedCarpet matches Operation above, RedCarpet shall first matchOperation and Form Type, and then only Operation.See RedCarpet Online Help for additional information on the ManageTransformation page.Web Service 141

RedCarpetAppendix ASample CodeListed below is a C++ code example of the available methodcalls.Each form download method is executed (tested) based on thebooleans set on page 14.using System;using System.IO;using System.Text;using DownloadRCForms.Eprise;namespace DownloadRCForms{/// /// Summary description for Class1./// class theApp{public static int FindObjectidColumn(String[]columns){for (int i = 0 ; i < columns.Length ; i++){if (columns[i].IndexOf("ObjectId")==0)return i;}return -1;}/// Web Service 142

RedCarpet/// The main entry point for the application./// [STAThread]static void Main(string[] args){try{PSWebService service = new PSWebService();service.Url = "https://example.silkroadtech.com/eprise/WebServices";String sessionnum =service.LogIn("Jim.Forms_Admin","$123xyz$","");if (sessionnum == ""){Console.WriteLine("Could not log in. Be sure password and URLare correct");return;}Eprise.EpsTableEx t =service.GetFormsIDs(sessionnum,"","","","","","","");int nObjectid = FindObjectidColumn(t.Data[0]);if (nObjectid

RedCarpetfor (int i = 1 ; i < t.Data.Length ; i++){if (bDownloadXML){Eprise.EpsStringEx ret =service.GetFormXML(sessionnum,t.Data[i][nObjectid]);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to retrieve xml for " +t.Data[i][nObjectid] + " Error:" + t.ErrorString);return;}String strXML = ret.Data;String strFileName =String.Format("c:\\downloadedforms\\Form{0}.xml",t.Data[i][nObjectid]);FileStream f = File.OpenWrite(strFileName);Byte [] arrBytes = ue.GetBytes(strXML);f.Close();}if(bDownloadPDF){f.Write(arrBytes,0,arrBytes.Length);Eprise.EpsBinaryEx ret =service.GetFormPDF(sessionnum,t.Data[i][nObjectid]);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to retrieve pdf for " +t.Data[i][nObjectid] + " Error:" + t.ErrorString);return;}Byte[] arrBytes = ret.Data;String strFileName =String.Format("c:\\downloadedforms\\Form{0}.pdf",t.Data[i][nObjectid]);FileStream f = File.OpenWrite(strFileName);f.Close();f.Write(arrBytes,0,arrBytes.Length);Web Service 144

RedCarpet}if (bMarkDelivered)}{Eprise.EpsStringEx ret =service.MarkFormDelivered(sessionnum,t.Data[i][nObjectid],"1");if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to mark form " +t.Data[i][nObjectid] + " Error:" + t.ErrorString);return;}if (bDeleteForm)}{Eprise.EpsStringEx ret =service.DeleteForm(sessionnum,t.Data[i][nObjectid]);if (ret.ErrorNum != 1){Console.Out.WriteLine("Error while trying to delete " +t.Data[i][nObjectid] + " Error:" + t.ErrorString);return;}}}catch(Exception e){}}}Console.Out.WriteLine(e.ToString());}Web Service 145