What kind of problems we solved and what kind of architecture decisions we made when building our ERP platform and new user interfaces

1. Accelerating Your SuccessAccelerating Your Success
APIFYING AN ERP
- ONGOING SAGA
Marjukka Niinioja
Senior Consultant & Manager
PlanMill Oy
Twitter: @mniinioja
www.planmill.com

2. Accelerating Your SuccessAccelerating Your Success
25+
COUNTRIES
100+
CUSTOMERS
20 000+
USERS
15
YRS BUSINESS
25
EXPERTS
2 M€
NET SALES (M€)
PLANMILL BRIEFLY
12.4.2016 2© 2014 PlanMill Ltd. I www.planmill.com
Our customers are the best in their breed and have
innovated a unique way of renewing their industry
Connected to PlanMill
Zapier

3. Accelerating Your SuccessAccelerating Your Success
ERP MEETS API
ERP: “Boring and heavy to manouvre”
APIfyid ERP: “Fast and Nimble”

4. Accelerating Your SuccessAccelerating Your Success
WHY API IS IMPORTANT FOR AN ERP?
• 3examples about pre- and post-API integrations
coming up:

5. Accelerating Your SuccessAccelerating Your Success
SIMPLE SYNCH BETWEEN A 3RD PARTY
CONTRACT MANAGEMENT AND ERP
“How much does it cost to make an SFTP + CSV integration, where we might want to transfer
customer’s basic information to our new contract management system?”
Just as you have given a quote or possibly implemented it, the customer needs something
more. Then another customer needs something a bit similar, but of course the data formats are
different and columns need to be in a bit different order. Oh, and you have to include 15
custom fields in there, too.
Pre-API: 100–2000 lines of custom non-reusable code and settings, done by you to extract the
file. In addition, setting up, testing and monitoring the SFTP.
Post-API: Everything including custom fields and metadata of field values comes out of the API.
A generic transformation layer of data and you can pick out the fields you need. Depending on
tooling and generic solution, 100–500 lines of fully re-usable code, either at your end, in
an IaaS, or in the 3rd party system.

6. Accelerating Your SuccessAccelerating Your Success
A BIT MORE COMPLEX EXAMPLE WITH AN ON-
PREMISE ITSM (IT SERVICE MANAGEMENT)
SYSTEM:
“How much does it cost to integrate our new ITSM system to
your system, it’s an on-premise solution with limited access
from outside, we are a couple of countries to the South from
you and actually we need it yesterday. Couldn’t you just cook up
a nice CSV we could use to synchronize pretty much all core
data umpteen times a day to both directions?”
Pre-API: 5 days of development, probably half of it on-site
Post-API: “Give this API documentation to your integration party, contact us if you have
questions”

7. Accelerating Your SuccessAccelerating Your Success
“SIMPLE” IMPORT
“A part of our business is SaaS but we also sell professional
services and such. Can we somehow import the SaaS-related
transaction costs from our other systems to your system monthly
so we can invoice them from our customers? We would really
like everything to be handled through one system.”
Pre-API: At least 3–5 days of specifications, comparing data
models, testing etc.
Post-API: “Here is our use case-specific, but still generic import
documentation. Check that and decide if you want to do the
import by manually uploading the files, or if you want to
integrate with our API”

8. Accelerating Your SuccessAccelerating Your Success
COMMON API UX PROBLEMS WE HAVE
ENCOUNTERED
• Why 5 requests, can’t I do it in 1 API
• Someone send 10 requests per ms – the system is stuck
• Backend is relying too much on the front end
• Yes this thing about filtering requests has been
documented - didn’t you find it?
• I don’t want to get stacktraces as error messages in the
API response
• I want to see the id in the response of the thing I just
created

9. Accelerating Your SuccessAccelerating Your Success
NEW IMPROVED PROCESS FOR THE API 2.0
Research
project
Customer &
Partner needs
and insights
Piloting
technologies
& 1st service
Demos,
knowlegde
sharing &
discussions
Arch. vs.
strategy what
services, how
to monetize
Internal beta
Eat own
dogfood with
new UI clients
Public beta
1.5 + involve
dev
community
Feedback
from
developer
community
Publish 2.0
WE ARE
HERE

10. Accelerating Your SuccessAccelerating Your Success
PLANMILL 16 UI CHANGES
- NOT POSSIBLE WITHOUT API

11. Accelerating Your SuccessAccelerating Your Success
OUR ARCHITECTURE CHOICES 1/3
• Authentication: HMAC over OpenID Connect (at first go)
– We need to improved our unified identity management
– Customers were more interested in “system integration” than authorizing individual
users
– Now we see tooling has developed and OpenID Connect is expected and feasible
• Data format: JSON over XML
– JSON is more UI development friendly and easier to parse
– also PDF & CSV available from reporting endpoints
• All other HTTP verbs properly used, not PATCH
– JSON delta would be cool, but we need to improve our persistence layer first.
– Most users or IaaS –providers don’t even know how to use proper PATCH

12. Accelerating Your SuccessAccelerating Your Success
OUR ARCHITECTURE CHOICES 2/3
• Documentation: RAML over Swagger
– New, standard, easy to adopt
– easy to generate documentation
– Easy to even generate SDK:s in various languages
– REST over SOAP
– SOAP has it’s uses also in our platform for invoice, account and
payroll transactions, as described by http://nordicapis.com/rest-vs-
soap-nordic-apis-infographic-comparison/
• Some custom headers like x-PlanMill-Currency
– Used to convert all money amounts to requested currency
• Both developer and end-user friendly error messages &
codes
– /enumerations?section=System.API.Errors

13. Accelerating Your SuccessAccelerating Your Success
OUR ARCHITECTURE CHOICES 3/3
• Batch
• Hooks
• Integrations

14. Accelerating Your SuccessAccelerating Your Success
BATCH OPERATIONS
Submit multiple API requests as a batch operation.
PUT /batch
BODY:
[ { "destination": "projects", "method": "POST", "header": {
}, "body": { "name": “ABC deployment project" } },
{ "destination": "projects/2839831", "method": "POST",
"header": { }, "body": { "name": “Acme ERP project" } },
{ "destination": "projects/2839830", "method": "DELETE",
"header": { }, "body": { } } ]

15. Accelerating Your SuccessAccelerating Your Success
HOOKS
• Designed according to http://resthooks.org/ “Stop That
Polling Madness” – manifest
• Work really well with services like Zapier & Google Cloud
Messaging, plus Apple’s and Microsofts messaging
• Hooks are subscribed to by the client and hooks trigger
when suitable event happens
• Example:
– /hooks
– { “id”: 2836851, “hook”: "timereport.delete", url:
"http://requestb.in/1cebrdl1", eventUser: -1, eventProject: -1 }

16. Accelerating Your SuccessAccelerating Your Success
THINGS WE NOTICED WE NEEDED WHEN
DEVELOPING UI
/enumerations
/languages
/meta
{ "filters" : [{ "name" : "freetextsearch", "caption" : "" },
{ "name" : "status", "caption" : "Status",
"values" : { "All" : "-1", "Locked" : "2", "Preliminary" : "4",
"Reported" : "0", "Accepted" : "1" } },
{ "name" : "billableStatus", "caption" : "Billable status",
"values" : { "All" : "-1", "In billing" : "4", "Billable" : "1", "Invoiced" :
"6", "Draft invoice" : "5", "Non-billable" : "3" }

17. Accelerating Your SuccessAccelerating Your Success
USING THE API: SOME DATA
CAN NOT ESCAPE – BUT MUST
BE SHARED VIA API
• Company Secrets – inside company &
immediate network
• Personal Data - Payroll integrations
– social security numbers
– sick leaves
– bank account & credit card numbers
– passwords
• Real Money – E-invoicing & Accounting
– invoices
– expense reports
– payroll

18. Accelerating Your SuccessAccelerating Your Success
RECOMMENDED READING
• http://nordicapis.com/is-your-api-the-cinderella-or-
the-crown-princess/
• http://nordicapis.com/apis-are-evolving-the-b2b-
landscape-2/

19. Accelerating Your SuccessAccelerating Your Success
MORE INFORMATION
Marjukka Niinioja, Senior Consultant & Manager
PlanMill Ltd.
Hämeentie 19, FI-00500 Helsinki
Tel: +358 40 838 7308
Email: marjukka.niinioja@planmill.com, sales@planmill.com
Website: www.planmill.com
Twitter: @Mniinioja, @PlanMill