REST API calls for tenant services
After installing the Incentives tenant service, you'll use an application like Postman to make REST API calls that initialize the database, create a model, and create users.
To call the endpoints, the header must be set with a JSON Web Token (JWT). You can use an online tool to generate the token if you input the payload and secret values.
header
{
"alg": "HS256",
"typ": "JWT",
"kid": "MANAGEMENT"
}payload
{
"admin_user": {},
"iat": 0,
"exp": 0
}The iat and exp fields are optional.
The exp field is an expiration date that must be set to a future date. The payload iat and exp are dates in Unix time as the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, not including leap seconds.
verify signature
The value you enter must match the value of MANAGEMENT_KEY in the restAPI.appsettings.config file. The default value is management-portal.
After you edit the payload and secret, copy the encoded token to paste into the Header section when you make REST API calls in Postman.
Example
Your JWT should look something like this after you've edited it:
Database initialization
After you have successfully installed tenant services, you must initialize the database that you created in PostgreSQL.
If you haven't already added a tenants database on postgres, you must do that before proceeding with the database initialization. Here are those instructions:
Adding a tenants database on postgreSQL
Open PG admin III and right click Databases to create a new database.
Name this database
tenants.Warning
The name of the database is case-sensitive.
Under the Schemas section of the new database, delete the public schema.
Later in the installation process, you'll create a new Incentives schema to replace this public schema.
Start the Rest API and tenant services.
In Postman, .
Tip
Add your requests to a collection so you can quickly find and make calls in the future.
In the Headers section of the request tab, add these keys, replacing
<JWT>with the JWT you generated:Key
Value
AuthorizationBearer <JWT>Content-Typeapplication/jsonYou will use the same headers for every call in this section, but you will have to add these keys to every new call.
Use this sample call to initialize the database:
Path: http://localhost:9100/services/createDB Method: POST Body: “NULL"
In Postman, the call should look something like this:
Click .
You should see a status of "200 OK" and a “success” message. This indicates that our DB has been initialized. Confirm this by opening up PG admin III. Notice that a new public schema has been created with all of the Incentives system tables.
Results
If successful, you will see a status of 200 OK.
You can confirm this by opening pgAdmin III and checking that a new public schema has been created with all of the Incentives system tables. In the sidebar, you should see something like this:
Model creation
To create a Incentives model, you must call the tenant services model creation endpoint.
Important
Ensure the SQL server is running when you create a model.
In Postman, .
Tip
You can copy the headers you added when you initialized the database.
Use this sample call to create a model, changing the parameters as needed:
Path: http://localhost:9100/services/admin/tenants/1/models Method: POST Body: { "Name":"string", "FiscalYearStart":"2020-01-01T00:00:00.000Z", "NbPayPeriods":12, "Currencies":[ { "m_shortName":"USD", "m_longName":"US Dollars" } ] }Important
Model names must start with a letter and cannot contain underscores.
Results
You should see a response that looks like this:
{
"model_id":0,
"model_name":"string",
"tenant_id":0,
"server":"1",
"database_name":"string",
"created_at":"2016-03-01T23:59:29.305Z"
}If successful, you will see a status of 200 OK.
You can confirm this by opening pgAdmin III and going to → and then right-clicking the table to . You should see the model you created in this list.
Model deletion
To delete a Incentives model, you must call the tenant services model endpoint.
Important
This call does not delete the model from the SQL server.
In Postman, .
Tip
You can copy the headers you added when you initialized the database.
Use this sample call to delete a model:
Path: http://localhost:9100/services/tenants/1/models Method: Delete Body: { "model_name":"string" }
Results
If successful, you will see a status of 200 OK.
Once a model is deleted, users cannot access it through the Incentives admin client.
Create administrator user
After creating your Incentives model, you must create an administrator user for your new model by calling a tenant services endpoint.
In Postman, .
Use this sample call to create a model, changing the parameters as needed:
Path: http://localhost:9100/services/admin/tenants/1/users Method: POST Body: { "tenant_id": "1", "email": "string", "password": "string", "first_name": "string", "last_name": "string" }
Results
If successful, you will see a status of 200 OK.
You can confirm this by opening pgAdmin III and going to → and then right-clicking the table to view the top 100 rows. You should see the user you created in this list.
Associate administrator user with model
After creating an administrator user, you must associate the administrator with your model.
In Postman, add a and use the same headers you used when you initialized the database.
Use this sample call to associate an administrator user with your model:
Path: http://localhost:9100/services/admin/tenants/1/users/<admin email address> Method: PATCH Body: { "tenant_id": "1", "email": "string", "model": "string" }Emailis the email of the administrator user that you created andmodelis the name of the model that you created.Caution
Remember to remove the
< brackets >when adding the admin email address.
If successful, you will see a status code of 200 OK.
You can confirm this by opening pgAdmin III and going to → and then right-clicking the table to . You should see a model listed under one of the users.