{"id":22712129,"url":"https://github.com/buildit/slink","last_synced_at":"2025-10-30T09:41:15.293Z","repository":{"id":78235763,"uuid":"137375781","full_name":"buildit/slink","owner":"buildit","description":"SmartRecruiters -\u003e SAP Integration","archived":false,"fork":false,"pushed_at":"2019-03-19T06:50:01.000Z","size":391,"stargazers_count":3,"open_issues_count":14,"forks_count":1,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-02-04T23:31:23.751Z","etag":null,"topics":["aws-cloudformation","aws-codebuild","aws-codestar","aws-lambda","codestar","sam-local","sap"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buildit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-14T15:21:13.000Z","updated_at":"2021-10-05T14:32:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"f2619f1d-315e-4ac4-bd71-d8b47d10889b","html_url":"https://github.com/buildit/slink","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildit%2Fslink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildit%2Fslink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildit%2Fslink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildit%2Fslink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buildit","download_url":"https://codeload.github.com/buildit/slink/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246250086,"owners_count":20747293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-cloudformation","aws-codebuild","aws-codestar","aws-lambda","codestar","sam-local","sap"],"created_at":"2024-12-10T13:09:29.328Z","updated_at":"2025-10-30T09:41:15.244Z","avatar_url":"https://github.com/buildit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Slink Project #\n_Slink_ is a SmartRecruiters to SAP integration service.  It is implemented using AWS Lambda, using the Javascript/Node \"flavor\", and is built and deployed using AWS' CodeStar CI/CD product.\n\n```\n                         +--------------------+\n                         |  CloudWatch Event  |\n                         +---------+----------+\n                                   |\n+------------------+               |\n| SSM Param Store  \u003c---------+     |  Scheduled Trigger\n+------------------+         |     |\n                             |     |\n                             |     |\n+-----------------+   GET   ++-----v------+    POST    +---------+\n| SmartRecruiters \u003c---------+    Lambda   +------------\u003e   SAP   |\n+-----------------+         +------+------+            +---------+\n                                   |\n                                   |\n                                   |\n                            +------v------+\n                            |   DynamoDB  |\n                            +-------------+\n                         (State/Medata/Stats)\n\n\n```\n\nA scheduled CloudWatch Event triggers the Lambda function, which queries SmartRecruiters for candidates in certain \nstates, converts them to \"applicants\", and then posts them to SAP, to either \"introduce\" them to SAP, or to \"activate\" \nthem in SAP.  Private/secret configuration data is obtained from Amazon's SSM Param Store.  Minimal data about the \nruns, introductions, and activations is (intended to be) stored in DynamoDB.\n\n\n# Building and Deploying #\n\n## Dependencies ##\n- Node 8.10+ / NPM 5.6.0+\n- It is highly recommended to use `nvm` [https://github.com/creationix/nvm]\n\n\n## Building Locally ##\n- Clone this repository\n- `nvm use`\n- `npm install`\n- `npm test -- --silent` (silent causes `console.log()` messages not to print, giving cleaner output)\n\n_Note_:  The solution was intended to be modular.  That is, there are can be several \"module\" subdirectories within \nthe source tree (though there is currently only one).  Each module is meant to represent a Lambda function and has \nits own `package.json`.  We were striving to keep the commands the same within a given module as within the project \nroot.  However, since `npm` does not support hierarchical project structures in the same way as say Java's Maven or \nGradle, when in doubt, run `npm` commands from within the module you're working with first, since that's what is \nactually built by the CI/CD pipeline.\n\n\n## Running Lambda Functions Locally via \"SAM Local\" ##\nThere is a CodeStar-managed CodePipeline in AWS that runs tests and deploys the function(s) in this package.  But what \nif you want to run/test locally?\n\n#### To Work with AWS from the command-line\n- [Install and configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) \n  (us-east-1 is recommended for your default region, at least for this project) \n- Test your installation:\n    ```bash\n    ❯ aws codestar list-projects\n    {\n        \"projects\": [\n            {\n                \"projectId\": \"buildit-slink\",\n                \"projectArn\": \"arn:aws:codestar:us-east-1:006393696278:project/buildit-slink\"\n            }\n        ]\n    }\n    ```\n\n#### To Execute Lambda Functions\n- Install and run Docker\n\n- [Install the SAM CLI](https://github.com/awslabs/aws-sam-cli#installation)\n\n- _Take special note of the requirement to add your project root directory to Docker's File Sharing preferences_\n\n#### To have a Local DynamoDb\n- [Download local DynamoDb](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)\n- Start local DynamoDb using Amazon's instructions\n- Run `./bin/create-local-tables.sh`\n- Map an IP so that the Lambda container can see the Dynamo instance (`localhost` won't work): \n\n  `sudo ifconfig lo0 alias \u003csome IP for Dynamo\u003e` (I use `10.1.1.22`)\n  \n  undo with\n  \n  `ifconfig lo0 -alias \u003csome IP for Dynamo\u003e`\n  \n- You should be able to do the following after these steps:\n    ```\n    ❯ aws dynamodb list-tables --endpoint-url http://\u003csome IP for Dynamo\u003e:8000\n    {\n        \"TableNames\": [\n            \"Activations\",\n            \"Introductions\",\n            \"LastRunDate\",\n            \"Runs\"\n        ]\n    }\n    ```\n    \n\n#### To run the Lambda\nSee [AWS docs](https://github.com/awslabs/aws-sam-cli#invoke-functions-locally).\n\nAdding up all the above, the command to run locally is:\n\n```$bash\nLOCAL_DYNAMO_IP=10.1.1.22 \\\nLAST_RUN_DATE_TABLE=LastRunDate \\\nRUNS_TABLE=Runs \\\nINTRODUCTIONS_TABLE=Introductions \\\nACTIVATIONS_TABLE=Activations \\\nsam local invoke SlinkMainFunction -e event.json\n```\n\n_**Note**_: Runtime configuration settings and secrets are manually managed in AWS Parameter Store. There are two sets of \nconfiguration settings for STAGE and PROD environments. When running locally via SAM local, the code automatically \nuses the STAGE configuration. The parameters are managed under the `/slink` path in AWS Parameter Store, as follows:\n\nPattern:\n`/slink/[environment]/grouping/name`\n\nExample:\n`/slink/STAGE/smartrecruiters/EMPLOYEE_PROP_ID`\n\n#### Troubleshooting\nIf you get a `Requested resource not found` error, then you probably screwed up your local DynamoDb setup.\n\n\n## AWS Deployment ##\nThe code is automatically built and deployed by CodeStar when code is committed to `master`.  Currently, branches\nare not built by the CI/CD system.\n\nPlease see the [CodeStar Dashboard](https://console.aws.amazon.com/codestar/home?region=us-east-1#/projects/buildit-slink/dashboard) \nto check deployment status.  \nContact a team member, if you don't have access.\n\n## Lambda \"Environments\" and Promotions ##\n\n### Environments ###\nLambda doesn't support environments per-se.  Instead, Amazon maintains a linear version history of a given Lambda's \ncode, and uses [\"aliases\"] (https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html) to tag versions.  \nAmazon maintains an alias called `$LATEST` that is automatically moved to a new version.  However, developers can\ncreate and use any number of aliases and then use the alias(es) to execute a given version of a Lambda.\n\nSpecifically for Slink, there is a `STAGE` alias that is automatically moved to the latest version of the function \non each successful build.  `STAGE` always corresponds to the `$LATEST` automatic alias.\n\nThere is a separate, _manually maintained_ alias called `PROD`.  The reason the `PROD` alias \nis moved manually is to allow for controlled promotion of the Lambda once it is proven out in staging.\n\nNote that the `PROD` alias is executed by the scheduled CloudWatch Event.  The `STAGE` alias can only be executed\nusing the Lambda's URL or in the Lambda console:\n\n`https://\u003csee codestart project page\u003e/Stage/slink`\n\n\n## Trivia and Gotchas ##\n\n#### Not all DynamoDB tables have code to populate them\n\n###### Activations Table\nIn the introduction process a new candidate is added to the SAP HR system, and an employee ID is handed back.  That\nemployee ID is then stored (PUT) in a SmartRecruiters custom property.  We don't want to introduce a given candidate more\nthan once.  A trick that we used to avoid re-introducing a candidate, without using DynamoDB, was to include the \ncandidate employee ID property when building an applicant.  Then, we just skip those applicants that already have \nan employee ID.  Obviously, this could have been achieved by storing in DynamoDB but the original approach a) fulfilled\nthe requirement to store the employee ID in SmartRecruiters, and b) didn't need DynamoDB to actually work (we wrote\nthis feature before adding DynamoDB to the mix of tech). \n\n###### Runs Table\nThe idea of the `Run` table was to capture statistics about a given run (basically stuff you see in the function's \nresponse).  One could imagine a simple API that would scan the run table and return to a CLI or web client.  We never \ngot to it, but decided to leave the table definition in place so at least the idea was captured.  There's no cost\n(that I know of) for an unwritten/read DynamoDB table.  \n\n#### Log messages are not separated by alias\nAWS doesn't magically write the function alias into log records that appear in CloudWatch logs.  Therefore, it's \ndifficult to be sure which alias' messages you're looking at.  We do write a log as the process starts, which looks\nsomething like this:\n```\n2018-07-18T15:52:51.979Z\ta04d0fd9-8aa2-11e8-9030-ad46d7b7496e\t#### Function ARN: arn:aws:lambda:us-east-1:000000000000:function:awscodestar-xxx-xxx-xxx-SlinkMainFunction-XXXXXXXX:STAGE \n```\nIt will be followed by the logs for that run, but there's nothing to prevent logs from being intermingled if another\ninvocation occurs.  There is a card to address this, but we never got to it.\n \n#### CodeStar is an odd beast\nCodeStar is basically a wizard that creates a repo, and a CI/CD pipeline pointing to that repo on your behalf.  It \nmagically starts building the code in your repo and deploying it.  However, it occupies kind-of an \"uncanny valley\" \nof automation.  If you wanted to move the project to a different region for some reason, that won't be straightforward:  \nyou can't just grab the CI/CD CloudFormation template and run it as-is, because it contains a CodeStar resource that \ncan't actually be created from CloudFormation (yeah, you will get an error message if you try). \n\nThat aside, there are some ways to have CodeStar point to a different repo than the one it originally created.\nIf you act as though you want to do an update on the CI/CD CloudFormation stack created by CodeStar, you'll see that\na couple of parameters refer to repository details (URL and token, at least).\n\n#### The Code in the project is not what CodeStar wanted us to have\nCodeStar created our Lambda/Node project using _Express_ for some reason, rather than just a handler method, as with\ntraditional Lambda/Javascript functions.  We converted it to just use `index.js::handler methods`.  Express seemed \nlike an additional level of indirection and complication that was not needed.\n\n\n#### Handy Local DynamoDB commands\n`aws dynamodb list-tables --endpoint-url http://localhost:8000`\n\n`aws dynamodb scan --table-name Activations --endpoint-url http://localhost:8000 --output text`\n\n`aws dynamodb delete-table --table-name Activations --endpoint-url http://localhost:8000`\n\nNote that you can delete a single table and then re-run the create script.  It will error out on the tables that\nare still present, but create any missing ones.\n\n## Team Practices ##\nSee (Contributing)[./CONTRIBUTING.md]\n\n\n# Original CodeStar Content    \n\u003cdetails\u003e\n\u003csummary\u003e\n  Click for more ...\n\u003c/summary\u003e\n\nThis sample code helps get you started with a simple Express web service\ndeployed by AWS CloudFormation to AWS Lambda and Amazon API Gateway.\n\nWhat's Here\n-----------\n\nThis sample includes:\n\n* README.md - this file\n* buildspec.yml - this file is used by AWS CodeBuild to package your\n  service for deployment to AWS Lambda\n* app.js - this file contains the sample Node.js code for the web service\n* index.js - this file contains the AWS Lambda handler code\n* template.yml - this file contains the AWS Serverless Application Model (AWS SAM) used\n  by AWS CloudFormation to deploy your service to AWS Lambda and Amazon API\n  Gateway.\n* tests/ - this directory contains unit tests for your application\n\n\nWhat Do I Do Next?\n------------------\n\nIf you have checked out a local copy of your repository you can start making\nchanges to the sample code.  We suggest making a small change to app.js first,\nso you can see how changes pushed to your project's repository are automatically\npicked up by your project pipeline and deployed to AWS Lambda and Amazon API Gateway.\n(You can watch the pipeline progress on your AWS CodeStar project dashboard.)\nOnce you've seen how that works, start developing your own code, and have fun!\n\nTo run your tests locally, go to the root directory of the\nsample code and run the `npm test` command, which\nAWS CodeBuild also runs through your `buildspec.yml` file.\n\nTo test your new code during the release process, modify the existing tests or\nadd tests to the tests directory. AWS CodeBuild will run the tests during the\nbuild stage of your project pipeline. You can find the test results\nin the AWS CodeBuild console.\n\nLearn more about AWS CodeBuild and how it builds and tests your application here:\nhttps://docs.aws.amazon.com/codebuild/latest/userguide/concepts.html\n\nLearn more about AWS Serverless Application Model (AWS SAM) and how it works here:\nhttps://github.com/awslabs/serverless-application-model/blob/master/HOWTO.md\n\nAWS Lambda Developer Guide:\nhttp://docs.aws.amazon.com/lambda/latest/dg/deploying-lambda-apps.html\n\nLearn more about AWS CodeStar by reading the user guide, and post questions and\ncomments about AWS CodeStar on our forum.\n\nUser Guide: http://docs.aws.amazon.com/codestar/latest/userguide/welcome.html\n\nForum: https://forums.aws.amazon.com/forum.jspa?forumID=248\n\nWhat Should I Do Before Running My Project in Production?\n------------------\n\nAWS recommends you review the security best practices recommended by the framework\nauthor of your selected sample application before running it in production. You\nshould also regularly review and apply any available patches or associated security\nadvisories for dependencies used within your application.\n\nBest Practices: https://docs.aws.amazon.com/codestar/latest/userguide/best-practices.html?icmpid=docs_acs_rm_sec\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildit%2Fslink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuildit%2Fslink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildit%2Fslink/lists"}