You are viewing limited content. For full access, please sign in.

Question

Question

Discussion: Will Laserfiche ever get a unified, "RESTful" HTTP API?

asked on January 23, 2020 Show version history

Many enterprise systems today, especially those that are cloud-based, have resource-oriented APIs that can be accessed over HTTP, which allow developers and system integrators to connect them to line of business software with relative ease. As the Laserfiche ecosystem grows, it is becoming more and more clear that one of the things holding it back is the lack of such an API. And frankly, it is confusing and somewhat concerning that there is nothing on the roadmap to develop one, at least as far as I'm aware.

Let me give a simple "real-life" example from just this week. We're working with a customer who uses a third-party cloud-based system to generate sales quotes as clean, professional-looking PDFs. The customer asked us if it is possible to store these PDFs automatically in a specific folder in Laserfiche, along with some metadata (template name, salesperson name and branch, and so on). The third-party system in question has webhooks that allow the generated PDFs to be sent elsewhere using HTTP POST, which allows the system administrator to easily configure a destination that can accept such requests and process them. The idea is that once a quote gets signed and accepted by the client, its PDF can then be sent to another system for archival.

The problem is that Laserfiche doesn't have anything that can ingest such requests. Getting it to do so would require writing a web service that utilizes the Laserfiche SDK behind the scenes, and writing and maintaining such services requires proficiency in .NET/C#, as well as familiarity with the service-oriented architecture of the LF ecosystem. Furthermore, there is no convenient method to authenticate the requests, so one either needs to be developed from scratch (LFDS doesn't have an open, standards-based protocol that can be consumed by non-LF applications, as far as I'm aware), or the web service needs to use the hard-coded credentials of a named user that has access to the destination repository.

The ideal solution would be a Laserfiche product/module (let's call it "LFAPI" for the sake of simplicity) that can be installed on a web server and configured to route requests coming to various endpoints over to their corresponding LF services. For example:

Fetch a document/folder: 
GET https://mydomain.com/lfapi/repositories/<repo_name>/<entry_id>

Store a document: 
POST https://mydomain.com/lfapi/repositories/<repo_name>/ (include document info in the request body, such as the image, metadata, options, etc.)

Update document metadata: 
PUT https://mydomain.com/lfapi/repositories/<repo_name>/<entry_id> (include desired updates in request body, e.g. metadata fields and values)

Invoke a workflow: 
POST https://mydomain.com/lfapi/workflows/<workflow_id> (include input params in the request body)

Get the status of a workflow instance: 
GET https://mydomain.com/lfapi/workflows/<instance_id> 

For authentication, you should be able to tie API Keys to user accounts, then include one as a bearer token in the request header for the LFAPI service to check and authenticate/authorize. Again, these types of authentication systems are super common; you get the idea.

To conclude, we always talk about how Laserfiche is easy to integrate with other systems, but I think everyone knows that that's just a half-truth — one that is becoming less true as time goes by. Sure, Workflow can send web requests, and read from and write to database tables and so on. But truly robust systems require two-way integrations, which means LF needs to be able to easily receive documents and data from outside as well. And currently the mechanisms for that need to be custom-developed, which makes them expensive and usually very clunky too because you always end up fighting the existing architecture and working around its design (not to mention licensing!) limitations. But if an "LFAPI" product existed — one that essentially acted as a unified gateway between Laserfiche and the outside world — it would immediately make Laserfiche a much, much more viable middleware piece in complex systems.

12 0

Replies

replied on January 23, 2020

Yes wink

 

8 0
replied on January 23, 2020

Color me intrigued! We used the SDK to build an API for basic functions like document and metadata retrieval, but our next "target" was going to be Workflow initiation.

0 0
replied on January 30, 2020

Just to be clear, you know Workflow already has an HTTP REST API for invoking workflows and querying their statuses, right?

0 0
replied on January 30, 2020

Yes, but to be totally honest the API help documentation hosted by WF doesn't provide much guidance on how to actually use it via pure HTTP requests. The whitepaper and most of the examples on Answers use C# activities to consume the web service rather than using JSON posts, so we were just going to go the code route and integrate the functionality into the API we built for document and metadata retrieval.

1 0
replied on January 30, 2020

Agreed completely Jason.

To be honest, Laserfiche should look at and get inspiration from the Stripe API, which has phenomenal documentation that makes it a joy to use. Notable points:

1. Documentation is publicly accessible, not hidden behind a login screen (or a module install, like with the LF SDK)

2. The page design is slick, coherent and modern.

3. Every object, function call (create, update, etc.) and parameter is explained in detail, with examples.

4. Examples available in multiple languages (since an HTTP interface enables client libraries to be written in any language)

If LF manages to create something like this, it would really move to the next level.

1 0
replied on January 30, 2020

Totally agree Ege - the Stripe API documentation is fantastic.

With that said, the Workflow Web Services REST API is fairly easy to use. I'd hate for you to unnecessarily reinvent that particular wheel.

I've attached a simple demo with two workflows bundled in a .wfi file. The first makes a web service call to invoke the other and pass an input parameter. You and Jason should have no trouble understanding it. Had to tack a .txt on the .wfi to get around file extension upload restrictions, so remove that after downloading. Import to any Workflow server and run the "[Web Service] Invoking WF" manually to see the demo in action.

You can view the actual Workflow REST API reference by going to the following address on a Workflow server with Workflow Web Services configured:
http://localhost/Workflow/api/help

Though it isn't as pretty as Stripe, the information is there. Example screenshots below.

Documentation root:

Invoking instances:

Hope that's helpful for now!

3 0
replied on January 30, 2020

Thanks Sam,

I have looked through the hosted reference page before, I guess I just never put a lot of time into testing it out and misunderstood some of the information. I think the biggest obstacle I had was trying to determine what minimum parameters are required and I believe there are a few where I wasn't sure of their purpose.

To be honest, it wasn't until recently that I even realized that you could create straight HTTP/JSON requests as I originally thought it could only be done through the web service client; this was obviously just a misunderstanding due to the Answers posts I had found at the time and the reference page indicating a client was needed to use services.

http://localhost/workflow/api/RestWorkflowAPI.svc

1 0
replied on January 30, 2020

Same, Jason. I have no idea how to make sense of that information, because as you say, what is required and what is optional is not clear. The first time I used the API I remember it took a ton of trial and error and it was very unpleasant, to say the least.

1 0
replied on January 6, 2021

Thank you Sam for your response and workflow to use and test. That was the most helpful thing I could find on the subject of trying to get a workflow to kick off with web services. The Laserfiche documentation is not great at all and I found the white page with the visual studio example not great either. My co-worker actually showed me Postman which is an amazing tool that's easy to use, free, and great for testing http GET, POST, and more requests. 

1 0
replied on June 24

I just downloaded this example workflow and tested it out, it works but I have some questions.

I have always known that the workflow API exists for Forms to connect to Workflow, but did not think it was available for outside use, this is because as far as I know there is no documentation for 3rd party use.

We have service provider interested in using it though.

Most important question I have is how do you authenticate? This example seems to rely on anonymous authentication.

Is there any documentation for authentication, method descriptions, required and optional fields or is it just you gotta know someone?

0 0
replied on June 24

The Workflow Web Service uses IIS's Integrated Windows Authentication. By default, Workflow grants privileges to the AD "Everyone" group which is why you didn't have to set any special permissions. 

A call made by either an AD user or another service running as a Windows/AD identity on the local (or a trusted) domain will typically respond to the auth handshake automatically. Calls from non-Windows/non-local systems are trickier. And unless you really, really know what you're doing security-wise, do not expose the Workflow Web Service to the public internet.

1 0
replied on June 24

Got it, so we could theoretically enable anonymous and allow access from a specific public IP address and/or request an API key (which would be checked server side to prevent others from successfully executing methods)

However it sounds like there is no documentation and it is not supported as a feature of Laserfiche, it was intended for Forms and other LF products to use only.

The use case is that we have a company which develops applications that collect data on a regular basis, nothing as simple as an online Form, it is a full scale application for a specific industry. The developers of this app, are interested in working with us to submit this data to an organization using Laserfiche for all their internal business operations.

Ideally they would like to use a REST API. However it sounds like LF does not include a REST API, only the utilities for calling other services APIs.

0 0
replied on June 24

If you're going to do that, you wouldn't and can't use Anonymous auth. Even though you could authenticate to the IIS endpoint itself, the Workflow service performs additional authorization checks where Anonymous auth will always fail.

Instead, you would create an AD service account for them, enable the IIS Basic Auth method, and have them pass the credentials for the AD account via Basic Auth in their call to the Workflow Web Service. It should go without saying that you must ensure the Workflow Web Service IIS endpoint is set up for HTTPS because otherwise those credentials are getting passed in plaintext. 

The Workflow Web Service is explicitly a REST API and it is documented. From one of my posts earlier in this thread:

You can view the Workflow REST API reference by going to the following address on a Workflow server with Workflow Web Services configured:
http://localhost/Workflow/api/help

1 0
replied on June 24

We would use TLS yes! Oh so that answers my question about authentication.

I have this site on our local workflow servers and have looked at it many times but can't find where to go to get the documentation.

http://localhost/Workflow/api/help 

It shows me a list of methods you can call, but when I click on them there is no description, or parameters. There really is nothing other than some huge examples using parameters I have not even learned yet and without any knowledge of what the method even does.

0 0
replied on June 24

Yep, that's the documentation. There are only five methods.

  1. Instances (CreateInstance) (POST) - Invokes a workflow instance. 
  2. Instances (CreateWorkflowInstance) (POST) - Invokes a workflow instance. I think the only difference between this and the first method is that this one lets you specify the workflow name in the URI itself rather than as a message parameter.
  3. Instances (QueueWorkflowInstance) (POST) - Queues a workflow instance (in practice you won't use this)
  4. Workflow (GetAllPublishedWorkflows) (GET) - Gets a list of published workflows and some info about each of them
  5. Workflow (GetParametersForWorkflow) (GET) - Gets a list of available input parameters for a specific workflow

 

You'll be using #1 or #2. Parameters that aren't in my simple example workflow set are generally not required. You can ignore the entire "formData" section as it's only used by Forms. Ignoring the Forms section leaves you with:

	"Initiator":{
		"Email":"String content",
		"InitiatorDisplayName":"String content",
		"InitiatorName":"String content",
		"IntiatorSID":"String content",
		"OtherProperties":[{
			"Key":"String content",
			"Value":{
				"boolean":true
			}
		}]
	},
	"InstanceCreationFlags":0,
	"Origin":"String content",
	"Originator":"String content",
	"ParameterCollection":[{
		"IsDebug":true,
		"Name":"String content",
		"Value":{
			"boolean":true
		}
	}],
	"RuleName":"String content",
	"StartingEntry":{
		"EntryGUID":"String content",
		"EntryId":2147483647,
		"FullPath":"String content",
		"Repository":"String content",
		"Server":"String content"
	},
	"Timestamp":"\/Date(928149600000+0000)\/",
	"WorkflowName":"String content",

I think most of those are self-explanatory. And again, if you're unsure what a parameter does, and it's not in my example workflow invocation API call, you probably don't need to worry about it.

1 0
replied on June 27

Thank you, this is super useful information for maybe some temporary internal projects, not sure if we should be using this for a proper 3rd party implementatio without support. Still really cool trick to know, your workflow examples worked perfectly and I could even pass a document over as a byte array.

I found that LF Cloud has a supported and documentated API so I am also going to mention it as an alternative.

1 0
replied on June 28

You should check the latest SP newsletter and look at the Integrations section of the latest SP product roadmap ;)

0 0
replied on January 23, 2020

Well said Ege. We get asked in almost every sales cycle if we have an API (REST or otherwise). We have built some projects using the WorkFlow WebService to receive documents and Metadata into LF but there are always challenges with supporting this as each is a one off. A true API would be so much better. Would be nice if we could have such an announcement at EMPower 2020.

2 0
replied on January 23, 2020

Would be nice if we could have such an announcement at Empower 2020.

 

 That does sound like a neat idea. 

3 0
replied on January 6, 2021

Laserfiche now has a REST API "preview" available for the repository (I assume workflow is coming later). As a VAR you should be able to get info about if from your Laserfiche Channel Manager. It looks like it will be available for Laserfiche Cloud first and is decently documented via the Swagger/OpenAPI specification.

2 0
replied on January 10

Here we are a year later and im asking the same question. Doesnt appear its moved out of Preview status for the API

0 0
replied on January 10

Hi Mike, 

The initial release of the Laserfiche API happened last year. We are continuing to add items to it iteratively and there's more to go, but it's certainly no longer in preview mode. Check out Laserfiche API for more information. 

1 0
replied on January 11

Directly from the Laserfiche website...

Where can I use the Laserfiche API?

The Laserfiche API is only available on Laserfiche Cloud.

My organization will never move to the Cloud, when can we get this kind of functionality with my on-prem installation? I was able to successfully START a workflow with an HTTP Post request but the workflow is only able to respond with a confirmation that the workflow started. I have multiple needs for an API call that could return an Entry ID with some search criteria so that I can open that document or return an entry not found message. One of my web apps just runs a search syntax as a web access URL but my web application doesn't know if there is a document or not until the user clicks the link. This would be a great use of an API so that my web app knows if there is a document in the repository or not. 

 

0 0
replied on January 11 Show version history

Ya they have old documentation online. In other places online (Like in their October release notes) it was mentioned they have Oauth stable now. I have a cloud application wanting to talk to their cloud application. I received new documentation yesterday outlining how the two systems can talk using a stable API (I cant use anything in a preview/alpha stage in production). Very excited for this. Your scenario does seem different though as I only want to be able to send files from my application to a repository within Laserfiche.

0 0
replied on January 11

Hi Lucas,

Try using Laserfiche SDK to develop an API https://support.laserfiche.com/product/sdk/ 

0 0
replied on January 11 Show version history

@████████are you familiar with the Laserfiche CMIS Gateway that ships with the Laserfiche SDK? It's a standards-based web service for repository actions. It has its quirks but would certainly allow you to programmatically check if there's a document somewhere or not. See:

Release Notes for the Laserfiche CMIS Gateway 10.4

List of Changes for Laserfiche CMIS Gateway 10.4

Easiest way to play around with it after installing the CMIS Gateway is with the Apache Chemistry CMIS Workbench. There are open source client libraries available through Apache in Java, Python, PHP, .NET, Objective-C, and JavaScript. You'll want to use the "Browser" (REST) binding, not the "Web Service" (SOAP) one.

0 0
replied on January 24

I am not familiar but very interested. We have a new system that is allowing us to create newer web-based apps so being able to call a web service from the borrowers to check for documents or return entry IDs so that I can open them directly from the browser would be awesome. 

I'll check out CMIS gateway since we did purchase the SDK so I should have access. Thank you. I'll let you know how that goes. I appreciate it. 

1 0
replied on October 23, 2020

Just added another request for workflow RESTful service, is it possible to designate a connection profile when start a workflow call?  

I post another question here:   https://answers.laserfiche.com/questions/180599/Workflow-Invoke-Workflow-select-different-connection-profile-possible

 

 

0 0
You are not allowed to follow up in this post.

Sign in to reply to this post.