External Integration Documentation

When integrating APIs into your Softools app, it's important to document the process thoroughly. This documentation is not only useful for fellow app builders but also serves as a reference for any future modifications you might need to make. Instead of relying on local storage or other methods to share this information, Softools offers a dedicated feature within the App Studio known as the ‘External Integrations’ area.

• Adding External Integration Documentation
• Process Map
• Integration Service
• Softools API Endpoints
• Implementation Method & Details

Adding External Integration Documentation

1. Navigate to the app containing the integration.
2. Click on the 'Advance' Folder.
3. Click on the 'Integrate' Tab.
4. To add your integration details, click the ‘Add External Integration’ button. This action will redirect you to a new page where you can document various aspects of the integration.

Process Map

This template provides a visual representation of the integration’s workflows, detailing the activities involved and identifying the responsible actors. These maps can be made in software like Power Point, Mirro and Figma Jam

To upload a diagram:

1. Click the edit icon beside the Process Map template.
2. Click the Upload icon, select your file, and confirm by clicking ‘OK’.

Integration Service

Here, you'll outline the specifics of the integration.

• Integration: Brief description of the integration
• Service: What external service are you integrating to
• Status: What is the current status of the integration
• Purpose/Feature Description: Brief Description explaining the integration
• Link to Resource: Link to the integration

Softools API Endpoints

If your integration utilizes Softools API endpoints, tracking them is advisable. To add an endpoint:

• Click ‘Add API Endpoint’.
• A pop-up will appear where you can enter details such as
  • Endpoint URL: Specify the URL of the API endpoint you are integrating. This is the primary link through which your app communicates with the API.
  • Authentication Email: Add the email associated with the API for authentication purposes. This is to know what record security the API will have access to.
  • Publicated API: This field is important for tracking whether the API is currently active, under testing, or deprecated.
  • Comments: Add any relevant comments or notes about the API endpoint. This could include usage tips, limitations, or any specific configuration details that might be helpful for future reference.

Implementation Method & Details

This section is designed to provide comprehensive insights into the functionality and interaction of the integration between different services. It helps in understanding the full scope of the integration and planning for future enhancements. Here’s how to document it effectively:

• Detailed Workflow:
  
  • Describe the step-by-step process of how data flows between services within the integration. Include any specific triggers, events, or conditions that initiate or affect this workflow. This detailed mapping helps in visualizing the operational aspects of the integration and aids in troubleshooting.
• Assumptions & Known Limitations:
  
  • Assumptions: List any preconditions or assumptions that the integration relies on. This might include specific configurations of the external services or expected data formats.
  • Known Limitations: Clearly state any constraints or restrictions you have encountered in the integration. This could involve limitations in API functionality, data synchronization delays, or any dependencies that might impact the integration’s performance or scalability.
• Future Improvement Ideas:
  
  • Suggest potential enhancements or optimizations that could be implemented in future versions of the integration. This could range from technical upgrades to improve efficiency, additional features to enhance functionality, or changes to overcome current limitations.

Once you have finished filling in all the information click onto the blue button ‘Save’. This will now save all the information written about the external integration onto this template for you or any other App Builders to refer to.