Best Practices and Tips

Authentication - Every API requires a loginName, password and tenantCod. The API results in an UnAuthorized exception if the user is not valid.

Audit Log - The application audit log displays each action performed based upon user.

Error Handling - Unlike DLRs, errors or exceptions thrown by the APIs need to be captured and necessary action taken. For example, if a user could not be created, It could be because the server was busy (overloaded) or because another user with the same user ID exists in the application.

When the API returns an error code, take action to handle the error. For example, the server was busy so you invoke Retry logic. Or, perhaps the failure occurred due to a duplicate user ID. You can capture details in the error in failure log. Details in the error failure log can be emailed.

An authentication failure may occur when there is an invalid username/password. If this is the case, a SoapException is produced by the API. A sample soap exception is provided below:

<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>
	System.Web.Services.Protocols.SoapException: Invalid username or password.
</faultstring>
<faultactor>https://qa.planful.com/PlanfulAPI/</faultactor>
</soap:Fault>

Data Validation Errors - Occur when there is a failure to validate data. This means that the success value in the return object is set to false and a related error message is included in it. A sample response returned by the CreateUser API where there is invalid user login is provided below:

<CreateNewUserResult>
<Code>11</Code>
<Success>false</Success>
<message>Login must be a valid email address. Only alphanumeric characters are allowed.</message>
</CreateNewUserResult>

If the user already exists in the tenant, the following occurs:

<CreateNewUserResult>
<Code>5</Code>
<Success>false</Success>
<message>User already exists in current tenant.</message>
</CreateNewUserResult>

When a user is created successfully, the following occurs:

<CreateNewUserResult>
<Success>true</Success>
<message>User Created Succesfully.</message>
</CreateNewUserResult>

Server Level Exceptions - Occur when the server is busy or experiencing other issues. In this case the client process needs to be retried three times before exiting the process.

Authentication and Authorization - This API requires a valid Planful user ID and password for authentication.

• Unique segment codes are needed. The dimension security API will not function correctly when there are duplicate segment codes. Only the first code found will be updated and the behavior cannot be predicted.

• All segments need to have codes updated. For instance, the Planful application creates root nodes without the code and only the name. The Services team needs to ensure that codes are updated for all nodes.

• After the dimension security API completes, Boomi needs to call the Process Dimension API as a task.

• Ensure that the reporting roles are alpha numeric and not created with numeric codes.

• Ensure that the user type (Native/SSO) field is not loaded with numeric values (this is a bug which will be fixed soon).