IBM Kenexa BrassRing on Cloud Talent Gateway Jobs API March 2017

What is an API? What can our API be used for and what can it pull back? API (application program interface) is a set of routines, protocols, and tools for building software applications. The API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components. What can our Talent Gateway Jobs API be used for? Pulling Req information via XML from the gateway to place out on other sites such as the Corporate Career Site, a microsite, or a Job Board. Creating a “deep link” to pre-defined search results. Creating an RSS feed to for your Corporate Career Site or a vendor hosted site. What can our Talent Gateway Jobs API pull back/show? The API will only be able to show information that is on the talent gateway. It will appear like a search that is completed on the talent gateway. However, you will be able to use a direct link; RSS feed; or XML to move that information to another site such as a Career page or a vendor’s page such as Indeed.com. Additional information regarding the Talent Gateway Jobs API can be found within the “IBM Kenexa BrassRing on Cloud Candidate TG API” document on the Support Portal.

How to Build a Talent Gateway Jobs API: Step 1 Enable the Client Setting: This task must be completed by an IBM representative if not already enabled.

How to Build a Talent Gateway Jobs API: Step 2 Enable the Talent Gateway Setting(s) - Tier 5+ users can complete this step. In Workbench > Click Tools > Talent Gateways > Edit the Talent Gateway you would like to run the query against > Enable the “Allow the Web service to query this gateway” (Optionally, you can also enable the Require encryption setting if you would like to encrypt your Jobs API.) > Save. During this step, make note of the Talent Gateway Site ID and Client ID (example below). The Client ID is specific to your account and is the same between Staging and Production. The Site ID will be unique per gateway and also per environment.

How to Build a Talent Gateway Jobs API: Step 3 Synchronize the Talent Gateways. Tier 5+ users can complete this step.

How to Build a Talent Gateway Jobs API: Step 4 Create a ‘Dummy’ User - BrassRing Admins can complete this step. When building the Jobs API, you will need to create a user specifically for the use of the API. You could use an existing user’s profile. However, if you do so, you run the risk that if that person’s account is ever inactivated due to leaving the company; the APIs will no longer work. It is recommended to create one ‘dummy’ user specific to the APIs that will not be inactivated. Once a user is created, you will not need to create the user again. Below are the steps to create a user. In BrassRing > Admin > Admin+ > Users > Add New User > Fill out all of the required fields plus the EMPLOYEE ID field. This will be important as it will be one of the IDs that the API will require. Tip: The Employee ID that you add should not be a valid ID within your organization or one that will ever be used.

How to Build a Talent Gateway Jobs API: Step 5 Look up Question IDs (QIDs) - Tier 5+ users can complete this step. Question IDs (QIDs) can be used in the API to limit the search results for a deep link, the jobs pulled back in an XML feed, or an RSS feed of jobs. For example, if you want a deep link that will show all jobs located in Nebraska for a vitual jobs map that your web development team is building, you can use the QID for your State field in the API to pull back only those jobs. Fields that you would like to filter on must be on the Search Jobs page of the Talent Gateway. Questions IDs (QIDs) can be used in the API to pull back information about the requisition in an XML feed. For example, if you want to pull back the Department, Location, Job Category, and Position Type, you can use the QIDs for these fields in the API to pull back the information that was entered on the req form. Fields that you would like to pull back information on must be on the Job Details page of the Talent Gateway. Look up the QID of the specific Req fields. In Workbench > Tools > Forms > Reqs > Req Forms > Click “Preview XML Talent Gateway Integration”

How to Build a Talent Gateway Jobs API: Step 5 Look up Question IDs (QIDs) - Tier 5+ users can complete this step. Make your selection from the list of Standard and Custom Req fields that are available > Click Preview XML Find the QIDs for each field. For example, the QID for the Location(s) field is 82883. Below is an example of where you can find them within the XML.

How to Build a Talent Gateway Jobs API: Step 6 Prepare the Tags by Collecting the IDs from Steps 2-5. Examples below. <Id>123456</Id> Is the Employee ID of the active dummy BrassRing user. (Step 4) <Credential>26286</Credential> Is the Client ID and is unique per client, but not per environment. (Step 2) <ClientId>26286</ClientId> Is the Client ID and is unique per client, but not per environment. (Step 2) <SiteId>6441</SiteId> Is the Talent Gatway site ID. This is unique per Talent Gateway, per environment. (Step 2) <OutputXMLFormat>0</OutputXMLFormat> The options for this XML node are: “0” if you would like XML returned “1” if you would like a RSS feed returned “2” if you would like a link (deep-link) returned <Id>82883</Id> Is an example of a QID of a field that exists on the Talent Gateway Job Details page and that you would like to have pulled back in the XML. These are unique per question, per environment. (Step 5) <Value><![CDATA[Lincoln, NE]]> Is an example of an option within the Locations field on the Talent Gateway. Adding an option, or options, to this CDATA section will filter the results that are returned. If you are wanting to filter by multiple options you will separate the options with a comma (<Value><![CDATA[Lincoln, NE, Boston, MA]]>). (Note: Use the DESCRIPTION of the option, not the code.) If you do not want to filter the results you will want the tag to read <![CDATA[TG_SEARCH_ALL]]>.

How to Build a Talent Gateway Jobs API: Step 7 Plug your IDs into the Sample Input XML below. This is a simple input XML that provides us a Link (deep-link) to jobs that are posted in “Lincoln, NE”. Additional samples can be found at the bottom of this PowerPoint. <Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>2</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Id>82883</Id> <Value> <![CDATA[Lincoln, NE]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

How to Build a Talent Gateway Jobs API: Step 8 Make the call. Access the appropriate Web Service Router URL: Staging Environment: http://stagingimport.brassring.com/WebRouter/WebRouter.asmx Production Environment: http://Import.brassring.com/WebRouter/WebRouter.asmx EU - Staging Environment: http://stagingkrb-jobs.brassring.com/WebRouter/WebRouter.asmx EU - Production Environment: http://krb-jobs.brassring.com/WebRouter/WebRouter.asmx Click “route” Place your XML into the “inputXml” field > Click Invoke

How to Build a Talent Gateway Jobs API: Step 9 Clean up the URL This is an example of the link (deep-link) option. Retrieve the URL from the returned XML. Example: https://sjobs.brassring.com/tgwebhost/searchresults.aspx?PartnerId=26286&SiteId=6441&Function=LinkQuery&LinkId=2405072 Remove the “amp:” values from the URL. https://sjobs.brassring.com/tgwebhost/searchresults.aspx?PartnerId=26286&SiteId=6441&Function=LinkQuery&LinkId=2405072

How to Build a Talent Gateway Jobs API: Step 10 Final Result when using the Link option in the XML: https://sjobs.brassring.com/tgwebhost/searchresults.aspx?PartnerId=26286&SiteId=6441&Function=LinkQuery&LinkId=240507 This link pulls back only jobs posted with a location of “Lincoln, NE”.

Other Sample XMLs XML: Pull back all jobs, via XML, that are posted on the Talent Gateway. This XML will contain the req information and a direct link to the job posting. (The direct URL will have to be cleaned up by removing the “amp;” values.) <Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>0</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Value> <![CDATA[TG_SEARCH_ALL]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

Other Sample XMLs XML: Pull back all jobs and specific field information, via XML, that is posted on the Talent Gateway. The resulting XML will include the direct link to the job posting. (The direct URL will have to be cleaned up by removing the “amp;” values.) <Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>0</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <ReturnJobDetailQues>3916,3920,3923,82883</ReturnJobDetailQues><ReturnLongJobDetailQues/> <Questions> <Question Sortorder="ASC" Sort="No"> <Value> <![CDATA[TG_SEARCH_ALL]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

Other Sample XMLs XML: Pull back all jobs, their full Job Descriptions, the Recruiter’s information, and the Hiring Manager’s information. The resulting XML will include the direct link to the job posting. (The direct URL will have to be cleaned up by removing the “amp;” values.) <Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>0</OutputXMLFormat> <JobDescription>YES</JobDescription> <IncludeAllRecruiterInfo>Yes</IncludeAllRecruiterInfo><IncludeAllHiringManagerInfo>Yes</IncludeAllHiringManagerInfo><Aut henticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Value> <![CDATA[TG_SEARCH_ALL]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

Other Sample XMLs Link: Creating a deep-link by filtering on/pulling back job search results for two options (within one field). <Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>2</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Id>82883</Id> <Value> <![CDATA[Lincoln, NE, Boston, MA]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

Other Sample XMLs Link: Creating a deep-link by filtering on/pulling back job search results for multiple fields. <Envelope version="01.00"> <Sender><Id>123456</Id><Credential>26286</Credential></Sender> <TransactInfo transactId="1" transactType="data"><TransactId>01/27/2010</TransactId> <TimeStamp>12:00:00 AM</TimeStamp></TransactInfo> <Unit UnitProcessor="SearchAPI"> <Packet> <PacketInfo packetType="data"> <packetId>1</packetId></PacketInfo><Payload><InputString> <ClientId>26286</ClientId><SiteId>6441</SiteId> <PageNumber>1</PageNumber><OutputXMLFormat>2</OutputXMLFormat> <AuthenticationToken/><HotJobs/> <ProximitySearch><Distance/> <Measurement/> <Country/><State/> <City/><zipCode/> </ProximitySearch><JobMatchCriteriaText/> <SelectedSearchLocaleId/> <Questions> <Question Sortorder="ASC" Sort="No"> <Id>82883</Id> <Value> <![CDATA[Lincoln, NE]]></Value></Question><Question Sortorder="ASC" Sort="No"> <Id>3916</Id> <Value> <![CDATA[Customer Service]]></Value></Question></Questions></InputString> </Payload> </Packet> </Unit></Envelope>

Questions?