Avtalsarbetsflöden i Node.js
Många affärsprogram och processer kräver dokumentation som förslag och avtal. PDF-dokument gör filerna säkrare och mindre ändringsbara. De har även stöd för digitala signaturer så att dina kunder snabbt och enkelt kan fylla i sina dokument. Adobe Acrobat Services Med API:er kan du enkelt införliva PDF-funktioner i dina webbprogram.
Vad du kan lära dig
I den här praktiska självstudiekursen lär du dig hur du lägger till PDF-tjänster i ett Node.js-program för att digitalisera en avtalsprocess.
Relevanta API:er och resurser
Konfigurera Adobe Acrobat Services
Kom igång genom att konfigurera autentiseringsuppgifter som ska användas Adobe Acrobat Services. Registrera ett konto och använd Node.js Quickstart för att verifiera att dina inloggningsuppgifter fungerar innan du integrerar funktionen i ett större program.
Först måste du skaffa ett utvecklarkonto för Adobe. Sedan, på Kom igång -sidan, väljer du Kom igång under Skapa nya autentiseringsuppgifter. Du kan registrera dig för en kostnadsfri demoversion som innehåller 1 000 dokumenttransaktioner som kan användas under sex månader.
På följande sida Skapa nya autentiseringsuppgifter uppmanas du att välja mellan PDF Embed API och PDF Services API.
Välj PDF Services API.
Ange ett namn för programmet och markera rutan med etiketten Skapa personligt kodexempel. Om du markerar den här rutan bäddas dina inloggningsuppgifter automatiskt in i kodprovet. Om du låter rutan vara avmarkerad måste du manuellt lägga till dina inloggningsuppgifter i programmet.
Välj Node.js för programtypen och klicka på Skapa autentiseringsuppgifter.
En stund senare börjar en .zip-fil att hämtas med ett exempelprojekt som innehåller dina inloggningsuppgifter. Node.js-paketet för Acrobat Services ingår redan i exempelprojektkoden.
Konfigurera exempelprojektet manuellt
Om du väljer att inte hämta ett exempelprojekt från sidan Skapa nya autentiseringsuppgifter kan du också konfigurera projektet manuellt.
Hämta koden (utan dina inloggningsuppgifter inbäddade) från GitHub. Om du använder den här versionen av koden måste du lägga till dina inloggningsuppgifter i filen pdftools-api-credentials.json innan du använder den:
{
"client_credentials": {
"client_id": "<client_id>",
"client_secret": "<client_secret>"
},
"service_account_credentials": {
"organization_id": "<organization_id>",
"account_id": "<technical_account_id>",
"private_key_file": "<private_key_file_path>"
}
}
För ditt eget program måste du kopiera filen med den privata nyckeln och inloggningsuppgifterna till programkällan.
Du måste installera Node.js-paketet för Acrobat Services. Installera paketet med följande kommando:
npm install --save @adobe/documentservices-pdftools-node-sdk
Konfigurera loggning
I exemplen här används Express för applikationsramverket. De använder också log4js för programloggning. Med log4js kan du enkelt dirigera loggning till konsolen eller ut till en fil:
const log4js = require('log4js');
const logger = log4js.getLogger();
log4js.configure( {
appenders: { fileAppender: { type:'file', filename: './logs/applicationlog.txt'}},
categories: { default: {appenders: ['fileAppender'], level:'info'}}
});
logger.level = 'info';
logger.info('Application started')
Ovanstående kod skriver loggdata till en fil i ./logs/applicationlog.txt. Om du vill att den ska skriva till konsolen i stället, kan du kommentera samtalet till log4js.configure.
Konvertera Word-filer till PDF
Avtal och förslag skrivs ofta i ett produktivitetsprogram, som Microsoft Word. Om du vill godkänna dokument i det här formatet och konvertera dokumentet till PDF kan du lägga till funktioner för programmet. Låt oss titta på hur du överför och sparar ett dokument i ett Express-program och sparar det i filsystemet.
Lägg till ett filelement och en knapp för att starta överföringen i programmets HTML:
<input type="file" name="source" id="source" />
<button onclick="upload()" >Upload</button>
Överför filen asynkront med hjälp av funktionen fetch i sidans JavaScript:
function upload()
{
let formData = new FormData();
var selectedFile = document.getElementById('source').files[0];
formData.append("source", selectedFile);
fetch('documentUpload', {method:"POST", body:formData});
}
Välj en mapp för att acceptera dina överförda filer. Programmet behöver en sökväg till den här mappen. Sök efter den absoluta sökvägen med hjälp av en relativ sökväg som har kopplats till __dirname:
const uploadFolder = path.join(__dirname, "../uploads");
Eftersom filen skickas via post måste du svara på ett post-meddelande på serversidan:
router.post('/', (req, res, next) => {
console.log('uploading')
if(!req.files || Object.keys(req.files).length === 0) {
return res.status(400).send('No files were uploaded');
}
const uploadPath = path.join(uploadFolder, req.files.source.name);
var buffer = req.files.source.data;
var result = {"success":true};
fs.writeFile(uploadPath, buffer, 'binary', (err)=> {
if(err) {
result.success = false;
}
res.json(result);
});
});
När den här funktionen har körts sparas filen i programmappen för överföring och är tillgänglig för vidare bearbetning.
Konvertera sedan filen från dess ursprungliga format till PDF. Exempelkoden du hämtade tidigare innehåller ett skript med namnet create-pdf-from-docx.js
för att konvertera ett dokument till PDF. Följande funktion: convertDocumentToPDF
, tar ett uppladdat dokument och konverterar det till en PDF i en annan mapp:
function convertDocumentToPDF(sourcePath, destinationPath)
{
try {
const credentials = PDFToolsSDK.Credentials
.serviceAccountCredentialsBuilder()
.fromFile("pdftools-api-credentials.json")
.build();
const executionContext =
PDFToolsSDK.ExecutionContext.create(credentials),
createPdfOperation = PDFToolsSDK.CreatePDF.Operation.createNew();
const docxReadableStream = fs.createReadStream(sourcePath);
const input = PDFToolsSDK.FileRef.createFromStream(
docxReadableStream,
PDFToolsSDK.CreatePDF.SupportedSourceFormat.docx);
createPdfOperation.setInput(input);
createPdfOperation.execute(executionContext)
.then(result => result.saveAsFile(destinationPath))
.catch(err => {
logger.erorr('Exception encountered while executing operation');
})
}
catch(err) {
logger.error(err);
}
}
Du kan märka ett allmänt mönster med koden:
Koden bygger ett referensobjekt och en körningskontext, initierar en åtgärd och utför sedan åtgärden med körningskontexten. Du kan se det här mönstret genom hela exempelkoden.
Genom att göra några tillägg till uppladdningsfunktionen så att den anropar den här funktionen, konverteras nu Word-dokument som användare laddar upp automatiskt till PDF.
I följande kod skapas målsökvägen för det konverterade PDF och konverteringen initieras:
const documentFolder = path.join(__dirname, "../docs");
var extPosition = req.files.source.name.lastIndexOf('.') - 1;
if(extPosition < 0 ) {
extPosition = req.files.source.name.length
}
const destinationName = path.join(documentFolder,
req.files.source.name.substring(0, extPosition) + '.pdf');
console.log(destinationName);
logger.info('converting to ${destinationName}')
convertDocumentToPDF(uploadPath, destinationName);
Konvertera andra filtyper till PDF
Verktyget för dokument konverterar andra format till PDF, som statiska HTML, en annan vanlig dokumenttyp. Verktyget tar emot HTML-dokument som paketerats som en .zip-fil med alla resurser som dokumentet refererar till (CSS-filer, bilder och andra filer) i samma .zip-fil. Själva HTML-dokumentet måste heta index.html och placeras i roten för .zip-filen.
Om du vill konvertera en .zip-fil som innehåller HTML använder du följande kod:
//Create an HTML to PDF operation and provide the source file to it
htmlToPDFOperation = PDFToolsSdk.CreatePDF.Operation.createNew();
const input = PDFToolsSdk.FileRef.createFromLocalFile(sourceZipFile);
htmlToPDFOperation.setInput(input);
// custom function for setting options
setCustomOptions(htmlToPDFOperation);
// Execute the operation and Save the result to the specified location.
htmlToPDFOperation.execute(executionContext)
.then(result => result.saveAsFile(destinationPdfFile))
.catch(err => {
logger.error('Exception encountered while executing operation');
});
Funktionen setCustomOptions
anger andra PDF-inställningar, till exempel sidstorlek. Här kan du se funktionen ställer in sidstorleken till 11,5 x 11 tum:
const setCustomOptions = (htmlToPDFOperation) => {
const pageLayout = new PDFToolsSdk.CreatePDF.options.PageLayout();
pageLayout.setPageSize(11.5, 8);
const htmlToPdfOptions =
new PDFToolsSdk.CreatePDF.options.html.CreatePDFFromHtmlOptions.Builder()
.includesHeaderFooter(true)
.withPageLayout(pageLayout)
.build();
htmlToPDFOperation.setOptions(htmlToPdfOptions);
};
När du öppnar ett HTML-dokument som innehåller vissa villkor visas följande i webbläsaren:
Dokumentets ursprung består av en CSS-fil och en HTML-fil:
När du har bearbetat HTML-filen får du samma text i PDF-format:
Lägga till sidor
En annan vanlig åtgärd med PDF-filer är att lägga till sidor i slutet som kan ha standardtext, till exempel en lista med termer. Document Toolkit kan kombinera flera PDF-dokument till ett enda dokument. Om du har en lista över dokumentsökvägar (här i sourceFileList
) kan du lägga till varje fils filreferenser till ett objekt för en kombinationsåtgärd.
När kombinationsåtgärden utförs tillhandahålls en enda fil med av källinnehållet. Du kan använda saveAsFile
på objektet för att behålla filen i lagringen.
const executionContext = PDFToolsSDK.ExecutionContext.create(credentials);
var combineOperation = PDFToolsSDK.CombineFiles.Operation.createNew();
sourceFileList.forEach(f => {
var combinedSource = PDFToolsSDK.FileRef.createFromLocalFile(f);
console.log(f);
combineOperation.addInput(combinedSource);
});
combineOperation.execute(executionContext)
.then(result=>result.saveAsFile(destinationFile))
.catch(err => {
logger.error(err.message);
});
Visa PDF-dokument
Du har utfört flera åtgärder på PDF-filer, men i slutändan måste användaren visa dokumenten. Du kan bädda in dokumentet i en webbsida med hjälp av Adobe PDF Embed API.
På sidan som visas i PDF lägger du till en <div />
element som innehåller dokumentet och ger det ett ID. Du använder detta ID inom kort. Inkludera en lista på webbsidan <script />
Hänvisning till JavaScript-biblioteket i Adobe:
<script src="https://documentcloud.adobe.com/view-sdk/main.js"></script>
Den sista kodbiten du behöver är en funktion som visar dokumentet när Adobe PDF Embed API JavaScript har lästs in. Skapa ett nytt AdobeDC.View-objekt när du får ett meddelande om att skriptet har lästs in via en händelse av typen adobe_dc_view_sdk.ready. Ditt klient-ID och ID för elementet som skapades tidigare behövs för det här objektet. Hitta ditt klient-ID i Adobe Developer Console. När du visar inställningarna för programmet som du skapade när du skapade autentiseringsuppgifter tidigare visas klient-ID:t där.
Andra PDF-alternativ
Inställningen Demo av Adobe PDF Embed API Här kan du förhandsgranska de andra alternativen för att bädda in PDF-dokument.
Du kan slå på och av olika alternativ och omedelbart se hur de återges. När du hittar en kombination du gillar klickar du på </> Generera kod för att generera den faktiska HTML-koden med dessa alternativ.
Lägga till digitala signaturer och säkerhet
När ett dokument är klart kan du lägga till digitala signaturer för godkännande med Adobe Sign. Den här funktionen fungerar lite annorlunda än den funktion du har använt hittills. För digitala signaturer måste ett program konfigureras för att använda OAuth för användarautentisering.
Det första steget när du konfigurerar programmet är att registrera ansökan om du vill använda OAuth för Adobe Sign. När du har loggat in går du till skärmen för att skapa program genom att klicka på Konto och öppna sedan ADOBE SIGN API och klicka på API-program för att öppna listan över registrerade ansökningar.
Om du vill skapa en ny programpost klickar du på plusikonen i det övre högra hörnet.
I fönstret som öppnas anger du ett programnamn och ett visningsnamn. Välj Kund för domänen klickar du på Spara.
När programmet har skapats kan du välja det i listan och klicka på Konfigurera OAuth för program. Välj alternativen. Ange programmets URL i Omdirigerings-URL. Här kan du ange flera URL-adresser. För programmet du testar är värdet:
http://localhost:3000/signed-in
Processen att använda OAuth för att erhålla en token är standard. Programmet dirigerar en användare till en URL för inloggning. När användaren har loggat in omdirigeras användaren tillbaka till programmet med ytterligare information från sidans frågeparametrar.
För inloggnings-URL:en måste ditt program skicka ditt klient-ID, din omdirigerings-URL och en lista över de omfattningar som behövs.
Mönstret för URL-adressen ser ut så här:
https://secure.adobesign.com/public/oauth?
redirect_uri=&
response_type=code&
client_id=&
scope=
Användaren uppmanas att logga in på sitt ID för Adobe Sign. När de har loggat in tillfrågas de om de ska ge programmet behörigheter.
Om användaren klickar Tillåt åtkomst På omdirigerings-URL:en skickar en frågeparameter med namnet code auktoriseringskoden:
https://YourServer.com/?code=<authorization_code>&api_access_point=https://api.adobesign.com&web_access_point=https://secure.adobesign.com
Genom att publicera koden på Adobe Sign-servern tillsammans med ditt klient-ID och din klienthemlighet får du en åtkomsttoken för åtkomst till tjänsten. Spara värdena i parametrarna api_access_point
och web_access_point
. Dessa värden används för ytterligare begäranden.
var requestURL = ' ${api_access_point}oauth/token?code=${code}'
+'&client_id=${client_id}'
+'&client_secret=${client_secret}&'
+'redirect_uri=${redirect_url}&'
+'grant_type=authorization_code';
request.post(requestURL, {form: { }
}, (err,response,body)=>{
var token_response = JSON.parse(body)
var access_token = token_response.access_token;
console.log(access_token);
});
När en signatur krävs för ett dokument måste dokumentet först överföras. Programmet kan överföra dokumentet till api_access_point
värde som togs emot när OAUTH-token begärdes. Slutpunkten är /api/rest/v6/transientDocuments
. Data för begäran ser ut så här:
POST /api/rest/v6/transientDocuments HTTP/1.1
Host: api.na1.adobesign.com
Authorization: Bearer MvyABjNotARealTokenHkYyi
Content-Type: multipart/form-data
Content-Disposition: form-data; name=";File"; filename="MyPDF.pdf"
<PDF CONTENT>
Skapa begäran med följande kod i programmet:
var uploadRequest = {
'method': 'POST',
'url': '${oauthParameters.signin_domain}/api/rest/v6/transientDocuments',
'headers': {
'Authorization': 'Bearer ${auth_token}'
},
formData: {
'File': {
'value': fs.createReadStream(documentPath),
'options': {
'filename': fileName,
'contentType': null
}
}
}
};
request(uploadRequest, (error, response) => {
if (error) throw new Error(error);
var jsonResponse = JSON.parse(response.body);
var transientDocumentId = jsonResponse.transientDocumentId;
logger.info('transientDocumentId:', transientDocumentId)
});
Begäran returnerar en transientID
värde. Dokumentet har överförts, men har inte skickats än. Om du vill skicka dokumentet använder du transientID
för att begära att få skicka dokumentet.
Börja med att skapa ett JSON-objekt som innehåller information om dokumentet som ska signeras. I det följande ska variabeln transientDocumentId
innehåller ID:t från koden ovan och agreementDescription
innehåller text som beskriver avtalet som måste signeras. De personer som ska signera dokumentet listas i participantSetsInfo
efter e-postadress och roll.
var requestBody = {
"fileInfos":[
{"transientDocumentId":transientDocumentId}],
"name":agreementDescription,
"participantSetsInfo":[
{"memberInfos":[{"email":"user@domain.com"}],
"order":1,"role":"SIGNER"}
],
"signatureType":"ESIGN","state":"IN_PROCESS"
};
Om du skickar den här webbbegäran skapas signeringsbegäran och ett JSON-objekt med ett ID för avtalsbegäran returneras:
request(requestBody, function (error, response) {
if (error) throw new Error(error);
var JSONResponse = JSON.parse(response.body);
var requestId = JSONResponse.id;
});
Om signerarna glömmer att signera och behöver ett annat e-postmeddelande skickar du meddelandena igen med det ID du fick tidigare. Den enda skillnaden är att du också måste lägga till deltagar-ID:n för parterna. Du kan hämta deltagar-ID:n genom att skicka en begäran om GET till /agreements/{agreementID}/members
.
Om du vill begära att påminnelsen skickas skapar du först ett JSON-objekt som beskriver begäran. Det minimala objektet kräver en lista över deltagar-ID:n och en status för påminnelsen ("AKTIV", "SLUTFÖRD" eller "AVBRUTEN").
Begäran kan även innehålla ytterligare information, till exempel ett värde för "anteckning" som visas för användaren. Eller en fördröjning (i timmar) att vänta tills påminnelsen skickas (i firstReminderDelay
), och en påminnelsefrekvens (i fältet "frequency"), som accepterar värden som DAILY_UNTIL_SIGNED, EVERY_THIRD_DAY_UNTIL_SIGNED eller WEEKLY_UNTIL_SIGNED.
var requestBody = {
//participantList is an array of participant ID strings
"recipientParticipantIds":participantList
,"status":"ACTIVE",
"note":"This is a reminder to sign out important agreement."
}
var reminderRequest = {
'method': 'POST',
'url': '${oauthParameters.signin_domain}/api/rest/v6/agreements/${agreementID}/reminders',
'headers': {
'Authorization': `Bearer ${access_token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(requestBody)
};
request(reminderRequest, function (error, response) {
});
Och det är allt som krävs för att skicka en påminnelsebegäran.
Skapa webbformulär
Du kan också använda API:et för Adobe Sign för att skapa webbformulär. Webbformulär låter dig bädda in ett formulär på en webbsida eller länka direkt till den. När ett webbformulär har skapats visas det också bland webbformulären i Adobe Sign Console. Du kan skapa webbformulär med UTKAST-status för inkrementell uppbyggnad, REDIGERINGSstatus för redigering av webbformulärfälten och ACTIVE-status för att omedelbart vara värd för formuläret.
Om du vill skapa ett webbformulär använder du formuläret transientDocumentId
. Bestäm en rubrik för formuläret och en status för att initiera det.
var requestBody = {
"fileInfos": [
{
"transientDocumentId": transientDocumentId
}
],
"name": webFormTitle,
"state": status,
"widgetParticipantSetInfo": {
"memberInfos": [ { "email": "" } ],
"role": "SIGNER"
}
}
var createWebFormRequest = {
'method': 'POST',
'url': `${oauthParameters.signin_domain}/api/rest/v6/widgets`,
'headers': {
'Authorization': `Bearer ${access_token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(requestBody)
}
request(createWebFormRequest, function (error, response) {
var jsonResp = JSON.parse(response.body);
var webFormID = jsonResp.id;
});
Nu kan du bädda in eller länka till ditt dokument.
Nästa steg
Som du kan se från snabbstarterna och den medföljande koden, är det enkelt att implementera PDF och digitala dokument godkännandeprocesser med hjälp av Node med Adobe Acrobat Services API:er Adobe API:er integreras sömlöst i dina befintliga klientprogram.
Om du vill identifiera de nödvändiga omfången för ett samtal, eller se hur samtalet skapas, kan du skapa exempelsamtal från Rest API-dokumentation. Inställningen Snabbstarter demonstrera även andra funktioner och filformat som Adobe Acrobat Services API:er och processer.
Du kan lägga till en mängd PDF-funktioner till dina program, så att användarna snabbt och enkelt kan visa och signera sina dokument och mycket mer. Börja med att kolla in Adobe Acrobat Services idag.