Create A HRM system specific contract

Integration Toolkit > Create A HRM system specific contract

This section provides guidance on developing the backend logic for Oneflow contract creation within your HRM system.

In the Get HRM Specific Data To Create A Contract section, you learned how to retrieve the required HRM-specific data for contract creation. This data should be passed to the contract creation function.

Create a Contract

To create a contract in Oneflow, you will need to specify the Oneflow workspace and template where the contract will be stored. To simplify this process, provide a list of available workspaces and templates for users to choose from.

📘
Note:
New workspaces and templates can only be created within the Oneflow application.

Refer to Get workspace from Oneflow and Get templates from Oneflow for instructions on retrieving workspaces and templates.

If the selected employee in your system doesn't have sufficient or has invalid data, Oneflow will fail to create the contract. In order to avoid this, ensure the required information for each employee (such as email, first name, last name, phone number, start date, work site, is stored and accessible). This data may vary depending on your HRM system.

FUNCTION CreateContract
	INPUT: user (includes API token and email), account_connection, body (contract detail)s)
	OUTPUT: contract_id (ID of the created contract)

	BEGIN
		# Step 1: Extract required data from the input body
		SET template_id TO value of 'source_id' in body
		SET workspace_id TO value of 'workspace_id' in body
		SET participants TO value of 'participants' in body
		SET contract_name TO value of 'contract_name' in body

		# Step 2: Prepare participant details
		Call AddParticipants to add participants to the contract

		# Step 3: Create the Oneflow contract
		TRY
			# Call the CreateOneflowContract function to create a contract.
			SET oneflow_contract TO CALL CreateOneflowContract USING template_id, workspace_id, counterparties, and contract_name
		CATCH Exception
			# Handle exceptions encountered during contract creation.
			HANDLE exception
		END TRY

		# Step 4: Return the contract ID
		Return the ID of the created contract
	END

To include additional company participants in the contract, add them as my_partyparticipants. For example, you might include a line manager, supervisor, or HR manager. In HRM system a participant who is to be employed can be referred to as Candidate/Employee/Talent/Contact. In the following example we will address candidate use case. However the candidate should be added as an individual party.

FUNCTION AddParticipants
    INPUT: participants (contains participant details, including candidate and my_party participants)
    OUTPUT: my_party (an object containing participants), parties (a list of party objects)

    BEGIN
        # Step 1: Initialize my_party object
        Initialize an empty object called my_party
        Initialize an empty list called my_party.participants

        # Step 2: Add additional my_party participants (if any)
        IF participants IS NOT EMPTY THEN
            TRY
                FOR EACH participant IN participants DO
                    SET participant_details TO {
                        '_permissions': { 'contract:update': participant_type != 'viewer' },
                        'name': participant.fullname,
                        'title': participant.jobtitle OR '',
                        'email': participant.email,
                        'phone_number': participant.phone_number,
                        'signatory': participant_type == 'signatory',  # Set signatory as boolean
                        'sign_method': participant.preferred_sign_method OR 'standard_esign',  # Default value
                        'delivery_channel': participant.preferred_delivery_channel OR 'email'  # Default value
                    }
                    # Add participant details to the my_party.participants array
                    ADD participant_details TO my_party.participants
            CATCH Exception
                # Handles exceptions encountered during my_party creation
                HANDLE exception
            END TRY
        END IF
		    
        # Step 3: Initialize parties list
        Initialize an empty list called parties
        
        # Step 4: Validate participants using the validation function
        CALL ValidateCandidateData to check all the required information are there

        # Step 5: Add the candidate as an individual counterparty
        TRY
            SET candidate TO {
                '_permissions': { 'contract:update': false },
                'name': candidate.fullname,
                'title': candidate.jobtitle OR '',
                'email': candidate.email,
                'phone_number': candidate.phone_number,
                'signatory': participant_type == 'signatory',  # Set signatory as boolean
                'sign_method': candidate.preferred_sign_method OR 'standard_esign',  # Default value
                'delivery_channel': candidate.preferred_delivery_channel OR 'email'  # Default value
            }
            # Add candidate details to the parties list with type set to IndividualCounterparty
            ADD candidate TO parties WITH type 'IndividualCounterparty'
        CATCH Exception
            # Handles exceptions encountered during parties creation
            HANDLE exception
        END TRY

        # Step 6: Return the parties list
        RETURN parties
    END

The ValidateCandidateData function ensures that all required fields are present for contract creation. If the selected employee lacks sufficient or valid information, Oneflow will fail to create the contract. To prevent this, validate that all required employee data is stored and accessible. For example, email and full name are commonly required fields, but you can adjust the mandatory fields based on your HRM system's needs.

FUNCTION ValidateCandidateData
    INPUT: participants (list of participant objects)
    OUTPUT: validation_result (either success or an error object)

    BEGIN
        # Step 1: Initialize validation result
        SET validation_result TO {'success': true}

        TRY
        # Step 2: Check if participants list is empty
        IF participants IS EMPTY THEN
            RETURN {'error': 'Participants list cannot be empty'}

        # Step 3: Validate each participant
        FOR EACH participant IN participants DO
            IF participant.fullname IS EMPTY OR participant.email IS EMPTY THEN
                THROW Exception('Participant must have a full name and email')
            IF participant.email DOES NOT CONTAIN '@' THEN
                THROW Exception('Invalid email format for participant: ' + participant.fullname)

        CATCH Exception AS error
        # Step 4: Handle validation errors
        SET validation_result TO {'error': error.message}

        END TRY

        # Step 5: Return validation result
        RETURN validation_result
    END

Function to create Oneflow contract:

FUNCTION CreateOneflowContract(template_id, workspace_id, my_party, counterparties, contract_name)
    # Purpose: Create a contract in Oneflow using the provided details.

    # Step 1: Prepare the request body
    CREATE body AS a key-value store WITH:
        "template_id": template_id,
        "workspace_id": workspace_id,
        "contract_name": candidate_name,
        "parties": counterparties

    # Step 2: Set up the headers for the API request
    DEFINE HEADERS
        SET "x-oneflow-api-token" IN HEADERS TO user.apiToken
        SET "x-oneflow-user-email" IN HEADERS TO user.email
        SET "Content-Type" IN HEADERS TO "application/json"

    # Step 3: Make the API request to create the contract
    SET response TO POST REQUEST TO "{host}/v1/contracts/create" WITH:
        - JSON body
        - SSL verification
        - HEADERS

    # Step 4: Check the response status code
    IF response.StatusCode EQUALS 200 THEN
        SET jsonResponse TO result of parsing response to JSON format
        RETURN jsonResponse
    ELSE
        THROW HttpResponseError
END FUNCTION

Create a Contract

📘Note:

📘
Note: