- 15.5
Web Service Architecture
The web service architecture acts as an intermediary between M4 Solutions and external applications. This offers the ability to standardize communication between systems with our customer’s networks. The web services are designed using JSON architecture.
Typically, the M4 API is hosted on a client’s application server. All calls to the API must use HTTPS. The base endpoint for the M4 is https://<domain>/m4api/api.
Dataflow Diagram
Technical Prerequisites
To access the M4 API, clients must have M4 Foundation and M4 Web Products of at least version 2017 installed and running on an application server. Both programs can be hosted on client servers or by Mapcom. Generally, Mapcom integration engineers will handle the installation and configuration of M4 Web Products and IIS. Once the application server and IIS are configured, third-party applications can request data from the API using the endpoints specified in the Knowledge Base.
Application Server Software Version Requirements:
- IIS version 7 or higher must be installed and enabled
- .NET framework 4.5.2 or higher must be installed
Authentication
Authentication is handled through one of two methods:
- Windows Authentication – Active Directory (preferred)
- SQL Server Authentication
When making calls to endpoints, applications should use basic authentication to send the user name and password for a valid account to the API. The user account utilized for authentication must exist in M4’s Users table to receive access to the API. Each client can use M4 Administrator tool to create and manage user accounts for M4.
Licensing
The M4 API controls access to specific methods through integration license codes assigned to each client’s instance of M4. Each integration license listed below grants access to specific API endpoints. Users should contact Mapcom support to authorize licenses for the specific API endpoints they need. The Home endpoint is open to all modules/integration licenses.
| Module/Integration Licenses | Associated Endpoint(s) | Prerequisite License(s) |
| Billing | Customer, CustomerServiceGroup, Feature, FeatureStatus, FeatureType, Service, ServiceStatus | Foundation |
| Workforce | Additional Charge, Additional Charge Type, Appointment, Project, Promotion, ServingArea, Ticket, TicketCategory, TicketCode, TicketNote, TicketPriority, TicketStatus, TicketType, TimeEntry | Foundation |
| Accounting | WorkOrder | Foundation |
| Circuits | Circuit, CircuitSize, CircuitStatus, CustomerNetwork | Foundation |
| CRM | Contact | Foundation |
| Element Management Systems | Alarm, CustomerEmergency | Foundation |
| Network Management Systems | Alarm, CustomerEmergency | Foundation |
| Locates | Foundation | |
| GPS | AVLListener, Vehicle | Foundation |
| Wireless | Foundation | |
| Inventory | Inventory | Foundation |
| Payroll | Foundation | |
| Assignment | AssignmentStatus, Element, ElementType, LineCard, LineCardElement | Foundation |
| Foundation | FileReference, Geolocation, Object, Structure, Plant, User | Foundation |
| Network Equipment Manager | NetworkEquipment | Foundation |
| Services Manager | ServicesManager | Foundation |
Endpoints
The M4 API separates the main data objects into the following endpoints. Each endpoint contains a set of methods which allow the API consumer to perform standard CRUD operations on data objects.
| API Endpoint Name | Description |
| Additional Charge | Contains methods related to managing additional charges |
| Additional Charge Type | Contains methods related to managing additional charge types |
| Alarm | |
| Appointment | Contains methods related to managing appointments for tickets |
| AssignmentStatus | Contains methods related to accessing M4 Assignment statuses |
| AVLListener | Contains methods related to tracking real-time truck location data |
| Circuit | Contains methods related to managing circuits |
| CircuitSize | Contains methods related to managing circuit sizes |
| CircuitStatus | Contains methods related to managing circuit statuses |
| CustomerNetwork | Contains methods related to managing customer networks |
| Contact | Contains methods related to managing contacts |
| Customer | Contains methods related to managing customer data |
| CustomerServiceGroup | Contains methods related to managing customer service group data |
| CustomerEmergency | Contains methods related to customer service outages |
| Element | Contains methods related to elements in M4. |
| ElementType | Contains methods related to element types in M4. |
| Estimate | Contains methods related to managing estimates |
| EstimateLineItem | Contains methods related to managing estimate line items |
| EstimateLineItemType | Contains methods related to managing estimate line item types |
| EstimateStatus | Contains methods related to managing estimate statuses |
| EstimateType | Contains methods related to managing estimate types |
| Feature | Contains methods related to managing service features |
| FeatureStatus | Contains methods related to managing the statuses of features |
| FeatureType | Contains methods related to managing the types of features |
| FileReference | Contains methods related to managing file references |
| Geolocation | Contains methods related to mapped elements |
| Home | Contains methods related to the current API version and user |
| Inventory | |
| LineCard | Contains methods related to plant for Assignment |
| LineCardElement | Contains methods related to plant for Assignment |
| M4MobileData | |
| NetworkEquipment | |
| Object | |
| Plant | |
| Project | Contains methods related to managing projects |
| Promotion | Contains methods related to managing promotions |
| Service | Contains methods related to managing customer services |
| ServiceStatus | Contains methods related to managing the statuses of services |
| ServicesManager | Contains methods related to available services |
| ServingArea | Contains methods related to serving areas |
| Structure | Contains methods related to managing structures |
| TicketCategory | Contains methods related to managing ticket categories |
| TicketCode | Contains methods related to managing ticket codes |
| Ticket | Contains methods related to managing tickets |
| TicketNote | Contains methods related to managing ticket notes |
| TicketPriority | Contains methods related to managing ticket priorities |
| TicketStatus | Contains methods related to managing ticket statuses |
| TicketType | Contains methods related to managing ticket types |
| TimeEntry | Contains methods related to managing time entries for tickets |
| User | Contains methods related to managing M4 users |
| Vehicle | Contains methods related to managing vehicles in the fleet |
| WorkOrder |