Quick Integration - Candidate Suppliers Help
The Candidate Suppliers quick integration import allows Hiperos 3PM users to directly upload spreadsheets via the HTTPS protocol.  This allows customers to perform inbound imports in an automated manner without the need of a user interface.  The various code snippets below provide working examples of how this is performed using a variety of popular programming languages.

The first row of the worksheet must include the field names as the column headers.  Hiperos 3PM Quick Integration reads this text to import the data to the appropriate fields.  NOTE: When importing setup data values, the setup code must be used rather than the display name.


Note: Required fields are marked with an asterisk (*).

Field Description
EngagementNumber (*) Engagement number of the Candidate Supplier. NOTE: this field is required but can be left blank if the EngagementName is populated. If both EngagementNumber and EngagementName are both included, EngagementNumber is used.
EngagementName (*) Engagement name of the Candidate Supplier. NOTE: this field is required but can be left blank if the EngagementNumber is populated.
ExternalReference (*) Enter the unique reference key to link to external systems (ERP system, etc). NOTE: this field is required but can be left blank if the SupplierName is populated.
SupplierName (*) Enter the name of the supplier. NOTE: this field is required but can be left blank if the ExternalReference is populated.
SupplierContactUserName (*) Hiperos 3PM username for the responsible individual at the supplier company. Can create a new user here, but existing users must be on the supplier. NOTE: Always required.
SupplierContactFirstName (*) First name for Supplier Contact. Can create a new user here, but existing users must be on the supplier. NOTE: Required only if creating a new user.
SupplierContactLastName (*) Last name for Supplier Contact. Can create a new user here, but existing users must be on the supplier. NOTE: Required only if creating a new user.
Status Indicates whether the candidate supplier is active and available to the R.Portal workflow (i.e., able to be enrolled in programs and engagements) or if the candidate supplier is inactive and unavailable to the workflow. Defaults to "Active" if blank on create. Valid values are "Active", "Inactive", or blank.
Rank Indicates how the candidate is rated (rank ordered) with respect to other candidate suppliers. Can be any positive integer starting with 0 and can go to anything above.
CandidateNotes Remarks/comments about the candidate supplier.
Awarded Indicates if the candidate supplier is awarded or not. Defaults to not awarded for new imports if left blank. Candidate Suppliers can be awarded though this import, but an award cannot be reversed. Valid values are "True" or "False". For a new import, if you do not want to award the Candidate Supplier right away, leave this blank for awarded being set to false.
udfs_<fieldname> Enter one column for each Candidate Supplier UDF to be entered. Enter the field name of the UDF to import in each column, and the value for each candidate supplier in the rows. Must match an existing r.portal UDF name for Candidate Suppliers. NOTE: field name must be in the format udfs_<fieldname>

Authentication

Valid credentials must be supplied for each Hiperos 3PM Quick Integration request issued in order to succeed.

The 3PM user supplied must be a member of either the 'QuickIntegration' group or the 'QuickIntegration-CandidateSuppliers' group.  The QuickIntegration group allows an account to access all Quick Integration resources.  The QuickIntegration-CandidateSuppliers group limits access to only the Quick Integration CandidateSuppliers resource.  If these groups currently do not exist in your Hiperos 3PM instance, please contact your local 3PM administrator or your Hiperos Customer Services representative to have them created.


HTTP Header Description
username Valid Hiperos 3PM Username
password Valid Hiperos 3PM Password

Content Type

The content type header must contain one of the following types listed below.  This is used to identify the file format that is being uploaded.  Note: If sending data as an octet-stream, filename is required in the Content-Disposition header.


Content Type Header File Type
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Excel 2007 or later versions (xlsx)
application/vnd.ms-excel Excel 2003 or earlier versions (xls)
text/csv Comma separated values (csv)
application/octet-stream File format determined by filename value in Content-Disposition
e.g. Content-Disposition: form-data; name="file"; filename="user_import.xlsx"
The following HTTP response status codes are utilized by quick integration to communicate import status back to the caller.  They are as follows...
Status Code Result Description
201 Created New objects succesfully created.
202 Accepted Data has been queued for import (system-generated e-mail confirmation to follow).
204 No Content No new or updated data to import was found or the file was not in the correct format.
400 Bad Request Problem rows and/or columns were found. Review returned validation message in response.
401 Unauthorized Username & password http headers were not found in the request.
403 Forbidden Login failed, was not found or not authorized.
500 Server Error Failed to save import data to database.

Java

package httpPostExample;

import java.io.File;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.HttpMultipartMode;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.mime.content.FileBody;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.protocol.BasicHttpContext;
import org.apache.http.protocol.HttpContext;
import org.apache.http.util.EntityUtils;

public class uploadFile
{
    public static void main(String[] args)
    {
        try
        {
            String url = "https://rportal.hiperos.com/QuickIntegration/CandidateSuppliers";
            String filePath = "c:\\hiperos\\outbox\\CandidateSuppliers_import.xlsx";

            HttpClient httpClient = HttpClientBuilder.create().build();
            HttpContext httpContext = new BasicHttpContext();

            HttpPost httpPost = new HttpPost(url);
            httpPost.setHeader("username""Your_3PM_Username_Here");
            httpPost.setHeader("password""Your_3PM_Password_Here");

            httpPost.setHeader("Connection""close");

            MultipartEntityBuilder builder = MultipartEntityBuilder.create();
            builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);

            final File file = new File(filePath);
            FileBody fb = new FileBody(file, "text/csv");

            builder.addPart("file", fb);

            final HttpEntity entity = builder.build();
            httpPost.setEntity(entity);

            HttpResponse postResponse = httpClient.execute(httpPost, httpContext);

            HttpEntity responseEntity = postResponse.getEntity();
            System.out.println(EntityUtils.toString(responseEntity));
        }
        catch(Exception ex)
        {
            ex.printStackTrace();
        }
    }
}

C#

using System;
using System.Net;

namespace QuickIntegration_Sample
{
    class Program
    {
        static void Main()
        {
            const string uriString = "https://rportal.hiperos.com/QuickIntegration/CandidateSuppliers";
            const string fileName = @"c:\\hiperos\\outbox\\CandidateSuppliers_import.xlsx";

            // Create a new WebClient instance.
            WebClient client = new WebClient();

            // Add authentication headers to request.
            client.Headers.Add("username""Your_3PM_Username_Here");
            client.Headers.Add("password""Your_3PM_Password_Here");

            // Upload the file to the URI.
            // The 'UploadFile(uriString,fileName)' method implicitly uses HTTP POST method.
            byte[] responseArray = client.UploadFile(uriString, fileName);

            string response = System.Text.Encoding.ASCII.GetString(responseArray);

            // Decode and display the response.
            Console.WriteLine("\nResponse Received.  The contents of the file uploaded are:\n{0}", response);
        }
    }
}