Service Submodule

Service submodule, ties-in different submodules together to orchestrate the business logic. An example pseudo code on what it does for this given service function: window.hapi.contract.service.getContracts()

• set loading true for contracts
• make a request to backend via API submodule function getContracts to get the array of contracts
• assign the contracts received from the API request
• set loading false for contracts

These service functions are automatically being run by the widgets, and you don't ever need to run them manually; however, these service functions provide some event callbacks that might be useful for your business use cases, such as knowing when a campaign order was successful so you can grab the ID of the created campaign.

Service functions have the following lifecycle events that you can use to add a callback listener:

• onStart: calls the provided callback with the arguments passed to the service function
• onSuccess: calls the provided callback with the return value of the service function (in most cases, the return value is the data returned from an API request)
• onFailure: calls the provided callback with the error that occurred during the service function execution
• onFinish: calls the provided callback with no arguments

Preventing actions using onStart event callback

In addition to running your callback listeners, the onStart callback provides a way to prevent function execution from proceeding. This is useful in cases where you want to pre-process the arguments passed to the service function and prevent execution if something is wrong. An example use case for this is, saving the campaign form to your database for archival/logging purposes. Still, if, for some reason, your own function that saves the form to the database fails, then the campaign is not ordered, so in other words, the transaction is rolled back, and the campaign order is not committed.

Loading...

Running service function yourself may come in handy in some cases such as migrating your existing contracts from another Contract management platform to VONQ VONQ HAPI Contracts.

Loading...

For example, to migrate your existing contracts, you could loop over the array of contracts you have mapped/transformed to VONQ contract structure and invoke the .run() function with the mapped/transformed contract form object that will handle validating and other parts of the business logic for you.

---

Using TypeScript types package for Service Submodule

We recommend that you use the global approach, as you won't need to do the service-only types approach:

Global approach

Read more about how to set types globally here

Service-only approach

To use the types for a variable of a service submodule, you would need to use HapiServiceFunctionWithLifecycleHooks generic type with the type argument of the function. Here is an example on how that can be accomplished:

1. Open Playground Service Submodule of a module here
2. On the very first few lines (most of the time second line), there is an import to the service.types.ts, jump to that file by CTRL (or CMD on Mac) + Click
3. Search by CTRL (or CMD on Mac) + F and type the name of the function createContract and you will find it in the respective type of the service submodule, in this case, WindowHapiServiceContract and the type is ContractServiceCreateContractHandler
4. Pass the type to the generic type as follows:

import {
    HapiServiceFunctionWithLifecycleHooks,
    ContractServiceCreateContractHandler,
    Contract
} from "@vonq/hapi-elements-types"

const createContractFnWithHooks = window.hapi.contract.service.createContract as HapiServiceFunctionWithLifecycleHooks<ContractServiceCreateContractHandler>
const createContractRunner = createContractFnWithHooks.run
const createContractOnStartListener = createContractFnWithHooks.onStart
const createContractOnSuccessListener = createContractFnWithHooks.onSuccess
const createContractOnFailureListener = createContractFnWithHooks.onFailure
const createContractOnFinishListener = createContractFnWithHooks.onFinish

// run the function
createContractRunner(
    //...the args expected in the type
)

// add success listener
createContractOnSuccessListener(
    (data: Contract) => { // type ContractServiceCreateContractHandler returns a Contract
        console.log('[HAPI] contract on success listener fired with data', data)
    }
)

---

For list of available services, check modules in the Playground.