Help with NT 14.13 API

[jking]

Hello,

     I'm having trouble getting started with a new API in my NT 14.13 app.  A laboratory will build an API on their end, and send an Institution ID (eg. S01) to my app.  I want my API to take this Institution ID and do a lookup into an Institution.tps file on my server. 

     If the Institution ID is found, I want to call an Insert to create a new record in an Enrollment.tps file.  During the insert and creation of a new record, a Study ID field will be created from the Institution ID and an autoincrementing field called Patient ID.  The Study ID, for example, would be something like S01-0001.  If a record is successfully created with this new Study ID, the Study ID then needs to be sent back to the client API.

     If the Institution ID is not found, then an error message must be sent back to the Client API.

     I have added a API service and method to my app but I'm struggling on what do add to the General, Parameters and Return tabs on the API Method template.  Can anyone provide me with some steps on how to proceed?

Thanks,

Jeff King

[Bruce]

Jeff,
this is likely a good question for the User Group Meeting on Thursday, because I have lots of questions for you.

But basically I start with
"Write your code in the ServiceMethod routine".

In other words write the code to do what you've laid out above. Then the parameters and returns become obvious (since they're used by, or created by, your code).

[jking]

Bruce,

     Found the registration at the top of the ClarionLive site.  I'll try to join on Thursday.

Jeff

[jking]

Hi Bruce,

     I have made quite a bit of progress with this.  My user will be coding the call to the API into their own application.  I'm stuck on one issue here.  I have a user file to check on valid users.  What if they use the header like "Authorization: Basic ZGVtbzpkZW1v", to pass the username and password.  Does NT resolve this for me or do I need to decode this in the Webhandler Authenticate embed?

Thanks,

Jeff

[jking]

Hi Bruce,

     The user asked me to try something.  In my EDC_Enrollment API method, I allow the user to do an insert into the Enrollment tps file.  Is there a way to make this conditional?  For example, they will pass an InstitutionID and I will do a lookup into the Institution tps file to see if it is valid.  I thought I might do this lookup in the InsertRecord:PatientEnrollment, Before Add embed.  See the attached image.  If the InstitutionID is not found, how can I stop the Insert action and send back an error message about the InstitutionID not being found?

Thanks,

Jeff

[Bruce]

>>  What if they use the header like "Authorization: Basic ZGVtbzpkZW1v", to pass the username and password.  Does NT resolve this for me or do I need to decode this in the Webhandler Authenticate embed?

The username and password are parsed out for you, and passed into the authenticate method as username and password parameters.
You then add code there to determine if you're happy with those credentials, or not.

[Bruce]

>> In my EDC_Enrollment API method, I allow the user to do an insert into the Enrollment tps file.  Is there a way to make this conditional? 

<< For example, they will pass an InstitutionID and I will do a lookup into the Institution tps file to see if it is valid.  I thought I might do this lookup in the InsertRecord:PatientEnrollment, Before Add embed.  See the attached image.  If the InstitutionID is not found, how can I stop the Insert action and send back an error message about the InstitutionID not being found?

In the spirit of "teach a man to fish" rather than just parrot out the answer, I think it will be helpful if you look at the generated code for the method, perhaps in the embeditor, and spend a bit of time understanding the flow.

There is a (very simple) solution - (hint - it involves p_web.AddServiceError) - but see where the InsitutionID is parsed, add your validation code there, and set an error if it's not valid.

[jking]

Hi Bruce,

     I've been on that "fishing trip" you recommended.  The following code is what I have come up with.  It is in the ServiceMethod Routine embed:


 Ins:Institution_ID = Enr:Institution_ID
 If Access:Institution.Fetch(Ins:InstID_key) = Level:Benign
    Set(Enr:PatID_key, Enr:PatID_key)
    Access:PatientEnrollment.Fetch(Enr:PatID_key)
    Enr:Study_ID = 'Z'&Enr:Institution_ID&'-'&Enr:Patient_ID
    Access:PatientEnrollment.Update()
 ELSE
    Access:PatientEnrollment.DeleteRecord(0)
    p_web.AddServiceError(999, '', '', 'Inst ID Not found', '')
 END


     To explain, the main goal is to use the API to do an insert on the PatientEnrollment table, and generate the Enr:Study_ID, which is passed back to the client. 

     The main problem here is the Enr:Patient_ID has an autoincrement key.  It seems the new autoincremented value of the Enr:Patient_ID is not available quickly enough during an insert, so it can be used in the construction of the Enr:Study_ID field. 

     For example, I set the passed in Enr:Institution_ID to 66, which is a valid ID in my test data, and the last Enr:Patient_ID is 1234.  After a successful Insert, I would expect the Enr:Study_ID to be:   Z66-1235.  However I get Z66-0.  Note that the insert seems to have autoincremented the Patient_ID properly as the correct value of 1235 is found in the PatientEnrollment table.

     So, my solution was to allow this partial record...that is a partial Study_ID...to be inserted and then I immediately open this record and update it with the properly constructed Study_ID.

     The other problem I found is,  when I pass an invalid Institution_ID, the API does return the proper error message I set in the above code.  However, the API still inserts a PatientEnrollment table record for this invalid Institution_ID.  I have not been able to conditionally prevent the insert, so again I delete the invalid record after the insert.

     To summarize, I'm still looking for a solution to get the next auto-incremented value of Patient_ID sooner.  Also, looking for a way to conditionally prevent the insert when the passed institution_ID is invalid.  My current solution of updating and deleting does give me the final results I'm looking for but it does seem a bit messy.

Thanks,

Jeff

[rjolda]

Jeff,
Something doesn't seem quite right here - something seems missing. You should be able to have your study record inserted and be able to get the values BEFORE returning a result.
When I am manually adding to a table I use the following code:
If Access:File.PrimeAutoInc() = Level:Benign
 Do stuff.
  !  needs an INSERT() to save the record here
.
The Primed fields (autonumbered) are available in the "Do stuff." section of the code BEFORE the Insert is called.
Not sure of exactly what you are trying to do but this might help you get in the right direction.
Ron

[Bruce]

ahh, the joys of auto-numbering. Boy am I glad I've left that behind. It's 'orrible.

I presume we're talking about client-side auto-numbering here?

Cheers
Bruce

[jking]

Hi Bruce,

     I'm confused by what you mean by client side auto-numbering.  This is an API that a "client" custom app will access.  This API has been added to an existing NT 14.13 server app we have had running for a few years.  The NT app does auto-numbering on a single field, the Patient_ID, on Inserts.  So I guess this would be server-side auto-numbering.

     However, based on Ron's recent post (Thanks Ron!), I changed my code.  I now have the following in the InsertRecordBeforeAdd embed of the InsertRecord:PatientEnrollment routine (NetWebServiceMethod):

    Ins:Institution_ID = Enr:Institution_ID
    If Access:Institution.Fetch(Ins:InstID_key) = Level:Benign
        Access:PatientEnrollment.PrimeAutoInc()
        Enr:Study_ID = 'Z'&Enr:Institution_ID&'-'&Enr:Patient_ID
    ELSE
        PatientEnrollment_Action = 'null'
        p_web.AddServiceError(999, '', '', 'Inst ID Not found', '')
    END

The use of the PrimeAutoInc() seems to have solved my auto-numbering issue.  I no longer have any code in the ServiceMethod routine embed.

     As you can see, I'm using the AddServiceError() in the ELSE statement above, as you hinted at in the previous post.  This does indeed send an error message as a result, when the passed Institution_ID is not valid.  However, a record is still created in the target tps file, PatientEnrollment.  This is the last issue I'm trying to solve.  A record should not be created in PatientEnrollment if there is not a valid Institution_ID in the Institution tps file.

     I thought I might be able to programmatically set the PatientEnrollment_Action variable, as seen in my code above.  So far this has not worked. 

Thanks,

Jeff

[rjolda]

HI Jeff,
I can't see all of your code.  However, it sounds like you are using 'built in'  action models.  i.e. You are calling for a record insert so that the system does attempt to do that.  You then test the condition later down the tree and if the patient is there - fine.  If not, you have an orphan record hanging around - sounds like that.

I have not played with the API yet _ but I am going to be getting very friendly with it later this week as it is on my schedule!  I would maybe HIJACK the code BEFORE the system does the requested INSERT ( Bruce usually leaves embeds around these things) and run your code first.  If no instituion then then you jump out BEFORE the actual insert and return them a message that it could not be completed.

My second thought is if the system has already primed I would consider something like:
IF SELF.Request = InsertRecord AND SELF.Response = RequestCancelled
   Access:MyFile.CancelAutoInc
END
This would "Undo" the Primed Inserted record.
Ron

[jking]

Hi Ron,

     I have tried a number of the embeds but still don't know exactly how to "jump out" before the Insert.  It is true, I'm using the "built in" action of Insert.  This particular API will only do Inserts but I want to conditionally do the Insert based on the presence of a valid Institution ID in a lookup of our list of institutions.
     I may be wrong but I thought using the p_web.AddServiceError to set an error message was a way to jump out of doing the Insert, but this has not worked for me. 

Stay Tuned!

Jeff

[rjolda]

HI Jeff,
I have found that looking at code in Embeditor Source is the best way to look at what is going on.  Also, at times I have gone to the NetTalk source clw files to chase down what it is doing....
I would think that there would be an api "action" setting - e.g. = Insert, Read (get), Delete.  I might attempt to Hijack a "READ" type API and manually do my checks and inserting and return a value.
In my thinking, I would not worry about sending and error message to an Institution which is NOT IN MY TABLES.  I would send a verification message about a "Valid Insert"
Ron

[jking]

Hi Ron and Bruce,

     Your suggestions have pointed me in the right direction.  I believe I have a solution.  I'm refining code and will report back when I think it is ready.

Thanks,

Jeff