Migrating Contracts

We already have a Contract managing solution but want to migrate all of the data to VONQ HAPI. Is there a bulk-import-like feature that we can use to accomplish this?

There is currently no import feature however, the goal of this "migration" can be accomplished through the HAPI Elements Javascript API. It is worth mentioning that it is going to require a huge amount of mapping on your side; however, it is still worth doing this mapping if you have thousands of contracts to migrate.

The process will include the use of several different HAPI Elements Javascript API submodules:

1. API submodule to get a hold of the Channel ID of the contract
2. API submodule to get a hold of the Channel's credentials
3. Validation submodule to validate your mapping is correct
4. API submodule to create contracts on HAPI backend

First, find the ID (VONQ's Channel ID) of the contract you want to map to:

try {
    const queryParams: Record<string, string> = {
        // if the below request does not return any results
        // try not to put the entire name but a section of it like if it is "LinkedIn Premium", then put "LinkedIn"
        search: "THE NAME OF THE CHANNEL"
    }

    const data = await window.hapi.product.api.getProductsSupportingContracts(queryParams)
    console.log('[HAPI][window.hapi.product.api.getProductsSupportingContracts] received response', data)
} catch (error) {
    console.error('[HAPI][window.hapi.product.api.getProductsSupportingContracts] received error', error)
}

data.results will have potential matches of Channels that VONQ has integration with. Find the IDs of the contracts you want to migrate to.

Once you have the channel you want to map to, get it's credentials structure:

try {
    const channelId = 14072 //Channel ID you obtained on the first step

    const data = await window.hapi.product.api.getProductSupportingContracts(channelId)
    console.log('[HAPI][window.hapi.product.api.getProductSupportingContracts] received response', data)
} catch (error) {
    console.error('[HAPI][window.hapi.product.api.getProductSupportingContracts] received error', error)
}

data returned from the response will be the channel in which there is contract_credentials array that contains objects with name field.

The contracts you have must be mapped to the VONQ HAPI's contract structure. To learn about VONQ's contract structure, refer to HAPI Backend Docs.

Let's consider your contract object looks like this:

const yourContract = {
    channel_name: "LinkedIn",
    company_id: "some-id",
    recruiter_contract_id: "some-id"
}

This should get mapped as such:

const vonqContract = {
    channel_id: 14072, //ID you obtained in the first step
    purchase_price: {
        amount: 100,
        currency: "USD" //check `currency` in HAPI Backend Docs linked above
    },
    credentials: {
        //these credentials are obtained on the second step
        Company_ID: yourContract.company_id,
        recruiter_contract_id: yourContract.recruiter_contract_id
    }
}

note

Please note that some channels require OAuth authentication (like Facebook). It works by sending the user to a new tab, to Facebook, where the user gives permissions and then gets redirected back to the application with the URL having a "hash" parameter with an encrypted hash. You can only create these contracts if you have the hash saved in the database. If you have the hash, you can map the hash programmatically, and the contract can be created.

To confirm that your mapping is working, run the validation against a single contract as such:

window.hapi.contract.validation.contractForm.parse(vonqContract)

Your mapped object is valid if you did not get any errors.

The last remaining step is to create the contract:

window.hapi.contract.api.createContract(vonqContract)

A full migration script would look something like this:

const aggregateOfYourChannels: any[] = [
    {
        name: "LinkedIn Premium Jobs",
        credential_1: "some-credential-1",
        credential_2: "some-credential-2",
        purchase_price_amount: 100,
        purchase_price_currency: "USD"
    },
    {
        name: "Adzuna",
        credential_1: "some-credential-1",
        credential_2: "some-credential-2",
        purchase_price_amount: 100,
        purchase_price_currency: "USD"
    },
]

const linkedInMapping = {
    Company_ID: "credential_1",
    recruiter_contract_id: "credential_2"
}

const adzunaMapping = {
    adzuna_credential_1: "credential_1",
    adzuna_credential_2: "credential_2"
}

for await (const channel of aggregateOfYourChannels) {
    let channelId
    try {
        const queryParams: Record<string, string> = {
            search: channel.name
        }

        const {results: channelResults} = await window.hapi.product.api.getProductsSupportingContracts(queryParams)

        // make sure to specify the Array index of the channel that you want to map to
        channelId = channelResults[0]?.id

        const channel = await window.hapi.product.api.getProductSupportingContracts(channelId)

        const mappedContract = {
            channel_id: channelId,
            purchase_price: {
                amount: channel.purchase_price_amount,
                currency: channel.purchase_price_currency
            }
            credentials: {}
        }

        Object.keys(channel.contract_credentials).forEach(credentialKey => {
            switch (channel.name) {
                case "LinkedIn Premium Jobs": {
                    mappedContract.credentials[credentialKey] = channel[linkedInMapping[credentialKey]]
                    break;
                }
                case "Adzuna": {
                    mappedContract.credentials[credentialKey] = channel[adzunaMapping[credentialKey]]
                    break;
                }
            }
        })

        window.hapi.contract.validation.contractForm.parse(mappedContract)

        await window.hapi.contract.api.createContract(mappedContract)

    } catch (error) {
        console.error("[HAPI] contract migration failed", error)
    }
}